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ABSTRACT 



A system and method for exchanging data between two or 
more applications includes a data exchange engine and a 
number of adapters associated with a corresponding number 
of applications. Each of the adapters is customized to 
interface with a corresponding application and transforms 
data being transferred between the application and the data 
exchange engine. Data produced by a particular application 
is converted from a technology dependent form to a tech- 
nology independent form by the corresponding adapter. In 
one embodiment, the format associated with a data stream is 
disassociated from the informational content of the data 
stream by the adapter. The informational content of the data 
stream is then transformed by the adapter into a common or 
generic format. The data exchange engine receives data in a 
technology independent form from each of its associated 
adapters and coordinates the routing of informational con- 
tent to particular adapters associated with applications that 
have requested specific informational content. The adapters 
receiving the informational content from the data exchange 
engine transform the informational content having the com- 
mon format into a data format compatible with, or specific 
to, their associated applications. A queuing mechanism is 
employed to construct a reliable asynchronous or pseudo- 
synchronous interface between disparate applications and 
systems. The data exchange engine may apply business rules 
or logic when processing a request for particular informa- 
tional content. User-specified routing logic may be applied 
by the data exchange engine to dispatch selected informa- 
tional content to one or more destination applications. 

56 Claims, 18 Drawing Sheets 
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DATA EXCHANGE SYSTEM AND METHOD 
FIELD OF THE INVENTION 

The present invention relates generally to information 
systems, and more particularly, to a system and method for 
exchanging data among dissimilar applications. 

BACKGROUND OF THE INVENTION 

A number of proposed solutions have been advanced to 
address the problem of effecting the communication of data 
between computer system platforms and applications devel- 
oped using distinctly different technologies. The increased 
reliance on distributed data processing systems and 
architectures, such as those employed to support Internet 
and Electronic Data Interchange (EDI) activities for 
example, has created a keenly felt need for improved meth- 
ods of transporting vast amounts of data of various types and 
formats between applications having dissimilar interface 
characteristics. 

In an attempt to address the problem of transporting 
dissimilar types of data between dissimilar systems and 
applications, various data interchange products and 
approaches have been developed. A traditional approach of 
electronically linking a number of disparate systems 
together involves the creation of custom gateways or inter- 
face systems. A typical custom gateway is created to solve 
a narrowly focused interface problem, such as permitting 
systems #1 and #2 to exchange data of types 'A' and <B* 
produced by systems #1 and #2, respectively. Such special- 
ized gateways are generally not intended nor designed to 
accommodate data interchange between a large number of 
disparate systems and applications. It is understood in the art 
that modifying an existing custom gateway to address a new 
and different interface problem is generally unproductive 
and costly, given the inherent limitations of the original 
gateway design. 

Various information technology standards have been 
advanced in an attempt to address these and other data 
interchange problems experienced within a distributed data 
processing and communications environment. One such 
standard, referred to in the art as CORBA (Common Object 
Request Broker), has received much recent attention, as it 
would appear to solve many of these problems. A critical 
review of the CORBA approach, however, reveals that 
CORBA is not designed to act as a data transport mecha- 
nism. Rather, CORBA is primarily designed to pass control 
methods over TCP/IP. The strength of CORBA is its ability 
to use C++ methods over a network. CORBA requires that 
all applications must be object oriented, which precludes 
inclusion of a substantial number of existing applications 
developed using structured programming techniques. 
Moreover, although CORBA is referred to as a "standard," 
there are several product implementations of CORBA which 
are not compatible, and as such, are incapable of commu- 
nicating with one another. 

Other technologies, such as transaction monitors, have 
been developed primarily to control complex transactions 
between multiple applications in a distributed processing 
environment. Such transaction monitors typically interface 
applications through rigorous transaction rules applied 
through defined IDL (Interface Definition Language) inter- 
faces across IPC (Inter Process Communication) methods. A 
typical transaction monitor has a complex structure that 
must be conformed to, and is complicated to use and 
maintain. If any one of the individual transactions that make 
up a transaction set fails, the entire complex transaction must 
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be backed out, rather than the single failed transaction. 
Transaction monitors are generally optimized for transaction 
control, and not for effecting data interchange. 

Fourth and fifth generation languages, termed 4GL and 

5 5GL, would appear to offer a partial solution to the data 
interchange problem. These and other similar languages, 
such as those used to construct "business objects," are 
optimized around the construction of applications and user 
interfaces for the primary purpose of providing powerful 

10 querying and reporting tools. The objects created by such 
languages typically define access paths to data residing in 
databases. The objects can be combined in various ways to 
create complex queries and for building powerful report 
generators. Fourth and fifth generation languages are not 

15 well suited for transporting vast amounts of data from one 
application to one or more other applications in a reliable 
and efficient manner. Although business objects constructed 
using 4GL and 5GL techniques do carry with them a certain 
amount of data, this data is typically data resulting from a 

20 query that is transported with an object definition for the 
purpose of performing additional analysis on the data. 

There exists a keenly felt need for a data exchange system 
and methodology that is capable of exchanging data of 
varying size, content, and format between dissimilar systems 

25 and applications. There exists a further need for such a 
system and methodology that is independent of any current 
or future technology. The present invention fulfills these and 
other needs. 

SUMMARY OF THE INVENTION 
The present invention is directed to a system and method 
for exchanging data between two or more applications. The 
data exchange system includes a data exchange engine and 
a number of adapters associated with a corresponding num- 

35 ber of applications. Each of the adapters is customized to 
interface with a corresponding application and transforms 
the data being transferred between the application and the 
data exchange engine. Data produced by a particular appli- 
cation is converted from a technology dependent form to a 

40 technology independent form by the corresponding adapter. 
In one embodiment, the format associated with a data 
stream is disassociated from the informational content of the 
data stream by the adapter. The informational content of the 
data stream is then transformed by the adapter into a 

45 common or generic format. The data exchange engine 
receives data in a technology independent form from each of 
its associated adapters and coordinates the routing of infor- 
mational content to particular adapters associated with appli- 
cations that have requested specific informational content. 

so The adapters receiving the informational content from the 
data exchange engine transform the informational content 
having the common format into a data format compatible 
with, or specific to, their associated applications. In one 
embodiment, a queuing mechanism is employed to construct 

55 a reliable asynchronous or pseudo-synchronous interface 
between disparate applications and systems. 

The data exchange engine may apply business rules or 
logic when processing a request for particular informational 
content. An application, for example, may require informa- 

60 tional content produced by a number of different applica- 
tions. The data exchange engine obtains, organizes, and 
processes the multiple source informational content as dic- 
tated by user-specific business logic. Changes to processing 
and organizational requirements for a particular user or 

65 application are effected simply by modifying the user- 
specific business logic, rather than data exchange engine 
code. 
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User-specified routing logic may be applied by the data FIG. 15 is an illustration of a Common Object in accor- 

excbange engine to dispatch selected informational content dance with one embodiment of tbe present invention repre- 

to one or more destination applications. As with the business sented in containment tree form; 

logic, changes in routing requirements are effected simply FIGS. 16A-16D illustrate the contents of a Common 

by modifying the routing logic, rather than data exchange 5 Attribute when used to represent various types of data 

engine code. supported in a Common Object of tbe type depicted in FIG. 

Process monitoring, tracing, and logging are provided to 15; 
track the progress of data passing through the data exchange FIG. 17 is an illustration of an inheritance tree graphically 
engine and to detect and correct processing errors. In the depicting a Common Base Class associated with the Corn- 
case of a processing anomaly, the data exchange engine l° mon object shown in FIG. 15; 

effects a rollback of failed transactions to preclude the loss FIG. 18 is a class structure diagram showing public and 

of data. Performance statistics may also be provided. non-public interfaces associated with various file based and 

A wide variety of interfaces may be developed by appro- database based queuing processes; 

priate deployment of adapters and one or more data piG J9 . g & pictorial description of the calling structure 

exchange engines. Proprietary back-end systems having between data exchange queue classes when dequeueing a 

only a single user-interface, for example, may be logically Q^m^ object in accordance with one embodiment of the 

transformed into an open system having multi-user Web m invention; and 

intefaces. Unreliable applications may be stabdi^d by description of the calling structure 

employment of the data exchange m rastructu e. Disparate P P ^ ^ a 

business systems whether they be archaic or Gbject in ac Ldance with the embodiment of FIG. 

may be effectively linked together to create electronic bond- wuwvu j 

ine gateways, for example. * . . . 

■tot above summary of the present invention is not While the .invention is amenable to various .modifications 

intended to describe ead, embodiment or every implemen- ^ and alternative forms specifics thereof have been shown by 

tation of the present invention. Advantages and attainments, 25 way of examp e in the drawmgs and wiU described „ 

together wi°h a more complete understanding of the detad here.nbelow. It is to be understood, ^eve^ that the 

invention, will become apparent and appreciated by refer- ™tenUon is not to limit the invention to the particular 

ringtothefoUowmgdetaUeddescriptionandclaimstakenin embedments descnbedjOn the contrary, the 

conjunction with the accompanying drawings. tended to cover all modifications, eqmvalents, and alter- 

J 30 natives falling within the spirit and scope of the invention as 

BRIEF DESCRIPTION OF THE DRAWINGS defined by the appended claims. 

FIG. 1 is a system level diagram of a data exchange ,, 4T1I ^ TT o 

architecture in accordance with an embodiment of the DETAILED DESCRIPTION OF THE VARIOUS 

present invention; EMBODIMENTS 

FIG. 2 illustrates in block diagram form the flow of data 35 j Q lhe f 0 u ow j n g description of the illustrated 

between disparate applications within information systems embodiments, references are made to the accompanying 

operated by two information service providers in accordance drawings which form a part hereof, and in which is shown 

with a conventional approach; wav 0 f illustration, various embodiments in which the 

FIG. 3 illustrates the deployment of a data exchange invention may be practiced. It is to be understood that other 

infrastructure within the information system environment of 4 embodiments may be utilized, and structural and functional 

information provider #1 shown in FIG. 2; changes may be made without departing from the scope of 

FIGS. 4 and 5 illustrate additional embodiments of a data me present invention, 

exchange infrastructure deployed to significantly enhance For purposes 0 f illustrating various features and advan- 

data interchange within existing information system envi- ^ tegcs wnen implementing a data exchange archi- 

ronments; tecture in accordance with the principles of the present 

FIG. 6 is a system block diagram of a data exchange invention, reference is made to the Figures, and more 

architecture in accordance with another embodiment of the particularly, to FIG. 1. In accordance with this illustrative 

present invention; embodiment, it is assumed that dissimilar applications, 

FIG. 7 is a depiction of a number of adapters operating in 5Q identified as Applications #1, #2, #3, and #4, produce 

cooperation to effect data exchange in accordance with one various types of dissimilar data. The term dissimilar appli- 

embodiment of the present invention; cations as used herein is intended to refer to applications that 

FIG. 8 is a detailed system block diagram of another differ in terms of technology, operation, supporting plat- 

embodiment of a data exchange architecture operating in forms and operating systems, data, input/output interfaces, 

accordance with the principles of the present invention; 55 communication protocols, and the like. The term dissimilar 

FIG. 9 illustrates additional details concerning various data is intended to refer to data types that differ in terms of 

control and queuing features of a data exchange architecture format, structure, protocol, content, and the like, 

operating in accordance with the principles of the present n js further assumed that each of the Applications shown 

invention; in FIG. 1 requires information produced by other Applica- 

FIGS. 10-11 are flow diagrams illustrating various pro- 60 tions. Application #3, for example, produces informational 

cesses involving the transport of data through a data content *C which is required by Application 'D,' and 

exchange engine in accordance with two additional embodi- requires informational content 'A' and 'B' produced by 

ments of the present invention; Applications #1 and #2, respectively. As such, each of the 

FIGS. 12-14 illustrate in flow diagram form various Applications, although representing distinctly different tech- 
processes involving the transport of data through a data 65 nologies which may be supported on distinctly different 
exchange engine in accordance with a further embodiment platforms, are dependent upon one another for various 
of the present invention; informational content. Those skilled in the art well appre- 
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ciate the difficulties of providing a mechanism to effect the exchange engine 32 facilitates the transport of the content 

required exchange of information between dissimilar Appli- < A' information to adapter 34b associated with Application 

cations while concurrently addressing a myriad of techno- #2. The adapter 346 reformulates the mformaUonal content 

logical interdependences. * A' having a common representation to a format E I repre- 

It can be appreciated that the traditional approach of s sentation which is compatible with Application #2 The 

implementing acustomized interface to effect the exchange adapter 34* in a similar manner reaves from the data 

of information between two disparate applications generally exchange en^ne 32 specified m onn^ional com eat A 

solves a narrowly focused communications problem, but reformulated from format A to the common or generic 

typically results in an inflexible solution intolerant to even format. Adapter 34d reformulates the mformaUonal conten 

shght changes in terms of format, frinction, or operation. 1Q <A' from the common representation to a type D format 

Prior art solutions to developing such interfaces to permit suitable for incorporation by apphcation #4. As is also 

communication between disparate applications are generally shown in FIG. 1, Application #3 requires selected informa- 

dependent upon the technologies inherent in either or both of tional content ' A from Application #1. The specified infor- 

the application software and/or platform hardware/software mational content 'A' is converted to generic form by the 

supporting the application. Such technology dependencies adapter 34a, transmitted through the data exchange engine 

are well-understood as significantly limiting the ability to 1 32 to adapter 34c, and converted to a format 'C* form for 

modify, expand, and scale an existing communications inclusion by Apphcation #3. 

infrastructure, and significantly complicates or even pre- It caQ ^ scen ^ Qm pjQ \ tnat disparate types of selected 
eludes the integration of new information sources and tech- daU may be e grf ect i ve ly and reliably transported between 
nologies. dissimilar applications with relative ease through employ- 
By way of example, and with further reference to FIG. 1, 2 ment of a daU excnan g e architecture in accordance with the 
it is assumed that Application #1 produces data of type 'A* principles of the present invention. The cooperative use of 
which may be viewed as constituting two constituent com- daplers assoc i a ted with specific applications in conjunction 
ponents. The term data, within the context of the environ- £ exchange engines either eliminates or 
ment illustrated in FIG. 1, is assumed to include an infer- ™* technology dependencies inherent in the 
mational content component and a format compnent. The 25 ~2f*ned through thf data exchange infrastructure, 
informational content component represents raw Udld "du&i^u ^ p, • - fi 
Irmat on typically business information, such as Such an implementation generally eliminates or sigmfl- 
accounting info^ationfor example. The format component cantly reduces the need for customed interfaces otherw^ 
typically Represents a technology-dependent construct that required to facilitate the transport of dissimilar "types of data 
provides a means for electronically interacting with the 30 between dissimilar applications. In other words, the tradi- 
informational content component. The format component, tional NxN connectivity problem associated with traditional 
for example may be defined to include data structures, interfacing approaches may be effectively reduced to a lxN 
protocols scripts, control codes, and other technology- connectivity scenario using a data exchange approach con- 
specific content. It is well appreciate in the art that many sistent with the principles of the present invention, 
so-called "compatible*' or "compliant" applications are in 35 To facilitate a better appreciation for the advantages 
truth inherently technology-dependent, thus precluding offered by the data exchange infrastructure implemented in 
seamless and reliable transport of information between two accordance with the present invention, reference is made to 
or more "compatible" applications. As was previously FIGS. 2-3. In FIG. 2, there is depicted a number of 
discussed, even standards-based applications are often inca- Applications, Applications #1 A -#N A > which interact within 
pable of communicating effectively with one another with- 40 an information systems environment operated by an infor- 
out intervening logic or protocol. mation provider #1. Information provider #2 operates an 
Returning again to FIG. 1, Application #1 produces data information system within which a number of disparate 
of type <A' which comprises informational content 'A' applications, represented by Applications tfl^-fN*, interact 
associated with a format 'A,' It is assumed in this illustrative in a specified manner. In addition to communicating mfor- 
example that Applications #2, #3, and #4 require selected 45 nation within each respective information systems 
portions of informational content < A' produced by Applica- environment, various types of information must be shared 
tion #1. The data exchange engine 32, in cooperation with between the two information providers #1 and #2. 
the adapters 34a-344 facilitate the exchange of required By way of example, and assuming that information pro- 
portions of informational content ' A in the following man- viders #1 and #2 provide telecommunications services, 
ner. In response to a request for particular data from Appli- 50 information provider #1 may represent a local exchange 
cation #1, selected data of type 'A' is transmitted to the carrier while information provider #2 may represent an 
adapter 34a. The adapter 34a processes the type ' A' data in inter-exchange carrier. It can be appreciated that the infor- 
such a way as to eliminate any technology dependencies mation system architecture associated with each of the 
associated with the type 'A* data. In particular, the adapter information providers #1 and #2 typically represents a 
34a disassociates the informational content component 'A/ 55 complex amalgam of archaic or legacy applications in 
alternatively referred to as informational content 'A,' from addition to state-of-the-art applications. This hybrid envi- 
its associated format component 'A,' and transmits only the ronment has generally led to an increased dependency on 
informational content 'A* to the data exchange engine 32. customized data exchange interfaces needed to facilitate 
In accordance with one embodiment of the present sharing of information between dissimilar applications 
invention the adapter 34a reformulates the informational 60 within a given information provider's operating environ- 
content < A' into a common or generic form which is subse- ment. Even simple modifications to a single application 
quently operated on by the data exchange engine 32. Each typically has significant upstream and downstream ramifi- 
of the adapters 34a-34d perform this process of reformu- cations which often require costly and specialized interfac- 
lating a technology-specific data stream into a generic or ing solutions. 

common data form. 65 In the illustrative embodiment shown in FIG. 2, it is 

Assuming that Application #2 requires selected informa- assumed that local exchange carrier #1 desires to enter the 

tional content * A' produced by Application #1, the data long distance market to expand its service and customer 
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base. The recently passed Telecommunications Act of 1996, 
however, mandates that local exchange carrier #1 provide 
equivalent access to its local loops which permits inter- 
exchange carrier #2 to gain access to the applications and 
information supported within the information infrastructure 5 
operated by local exchange carrier #1. In order to comply 
with federal regulation, local exchange carrier #1 must 
tolerate intrusion into its internal information systems by 
inter-exchange carrier #2. It can be appreciated that the 
conventional approach of constructing customized elec- 10 
tronic bonding gateways to facilitate communications 
between two dissimilar information provider environments 
would result in a costly and generally inflexible interface 
solution. 

A data exchange infrastructure implemented in accor- 15 
dance with the principles of the present invention greatly 
simplifies the task of interfacing numerous disparate appli- 
cations to facilitate reliable communication of information 
between two information provider environments such as 
those depicted in FIG. 2. As is shown in FIG. 3, a data 20 
exchange infrastructure in accordance with one embodiment 
of the present invention may be deployed to accommodate 
the access requirements of inter-exchange carrier #2 and the 
security considerations of local exchange carrier #1. 

This illustrative solution offers a number of advantages 25 
heretofore not attainable using conventional interfacing 
approaches. In particular, expandability, flexibility, and scal- 
ability is introduced into the information system environ- 
ment of the local exchange carrier #1 which was not ^ 
previously realizable using the original architecture shown 
in FIG. 2. Moreover, none of the applications or data 
supported or produced by the applications (i.e., Applications 
Ia-N^) need be changed when deploying a data exchange 
infrastructure in accordance with the principles of the ^ 
present invention. 

In this illustrative example, each adapter A-N is associ- 
ated with a corresponding data stream Dj-D^. Data stream 
D lt for example, may represent EDI data generated by 
Application #1 running on a back-end proprietary system. It 4Q 
is understood in the telecommunications industry that EDI 
represents a generally accepted standard for passing elec- 
tronic messages between telecommunications service pro- 
viders. However, it is also understood in the industry that 
various EDI dialects exist which necessitates some form of 45 
data transformation to occur in order to facilitate effective 
communication between back-end systems. 

Adapter A is configured to disassociate the informational 
content transported within the EDI data stream D} from its 
associated EDI format and dialect. The EDI informational 50 
content extracted by adapter A is reformatted to a common 
representation and then transported through the data 
exchange engine 62 to a destination application within the 
inter-exchange carrier #2 environment. The adapter 120, in 
this embodiment, is configured to translate the EDI infor- 55 
mation content having a common format to an EDI format 
and dialect required by the destination application. Adapter 
120 also converts source EDI information transmitted from 
inter-exchange carrier #2 into the common or generic form. 

The data exchange infrastructure depicted in FIG. 3 60 
effectively isolates the proprietary information and systems 
of local exchange carrier #1 yet provides the required access 
to inter-exchange carrier #2 mandated by current federal 
regulations. In addition, deploying the data exchange archi- 
tecture shown in FI G . 3 provides for the development of new 65 
interfaces not contemplated or easily achievable given the 
limitations of the original system architecture. For example, 
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an adapter, such as adapter W, may be deployed to facilitate 
communication and data exchange via the Internet. By way 
of further example, a Web browser interface may be devel- 
oped to convert a single-user interface of a proprietary 
back-end system to a multi-user, Web browser interface 
without the need to modify the back-end system or appli- 
cations running thereon. A Web browser interface, repre- 
sented as application WWW in Fig,. 3, may thus be imple- 
mented with little effort and cost. 

In FIG. 4, there is illustrated another embodiment of an 
information interchange environment within which the data 
exchange infrastructure in accordance with the present 
invention may find particular application. The data exchange 
infrastructure may be implemented to enhance workflow or 
process management systems which interact with any num- 
ber of legacy or proprietary applications, remote data stores, 
or various user and application work queues. In this 
embodiment, the data exchange infrastructure provides for 
reliable application integration, data movement, and remote 
work queues. In this configuration, unreliable system 
implementations, such as screen scraping applications or 
networks with poor line condition, may be transformed into 
reliable implementations through use of the data exchange 
infrastructure. In particular, this unreliable to reliable con- 
version is achieved, for example, through the use of persis- 
tent queues, rollback processing upon transaction failures, 
which provides for transactional integrity, and transaction 
retry processing as necessary. 

FIG. 5 depicts a data exchange infrastructure imple- 
mented within an existing information exchange environ- 
ment. In this illustrative example, a data exchange infra- 
structure is implemented to provide reliable interfaces 
between legacy or proprietary applications and newer 
interfaces, such as Web-based interfaces. In this regard, 
archaic or legacy applications may be provided with state- 
of-the-art interfaces to facilitate substantially enhanced user 
interaction. 

In this example, an EDI data stream is processed through 
the data exchange infrastructure as a received transaction 
initiated by a legacy or proprietary application. In response 
to a user inquiry, for example, selected data generated by the 
legacy or proprietary application is processed through the 
data exchange infrastructure to provide user access through 
a Web-based interface. As in previous examples, neither the 
EDI data nor the legacy/proprietary applications require 
modification, as all accommodations to dissimilar data for- 
mats and applications are provided for through the data 
exchange infrastructure. 

Referring now to FIG. 6, there is illustrated an expanded 
depiction of one embodiment of a data exchange infrastruc- 
ture implemented in accordance with the principles of the 
present invention. In this embodiment, the data exchange 
infrastructure provides for the effective and reliable trans- 
port of information among any number of disparate 
applications, data streams, and platforms associated with 
two or more information providers. Information provider #1, 
for example, produces data streams of various types which, 
when processed by associated adapters, are received by a 
data exchange engine 62 in a generic or common format. 
Associated with each of the data streams produced by 
information provider #1 is control or request information 
which is further processed by the data exchange engine 62. 
The information or raw data component associated with the 
control or request information is buffered in a data store 64. 

The data exchange engine 62 cooperates with a routing 
logic module 66 to determine one or more destination 
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applications within the information provider #2 systems 
environment that require particular data streams from infor- 
mation provider #1. It is noted that the content of a particular 
data stream, such as data stream A a , may have been 
requested by more than one information provider #2 appli- 5 
cation. Assuming that three such applications within the 
information provider #2 systems environment have 
requested all or selected portions of the data stream Aj 
content, three corresponding adapters are employed to con- 
vert the data stream Aj content from a generic format into 10 
corresponding pre -determined formats specified for the 
three destination applications. 

The data exchange engine 62 also cooperates with a 
business logic module 68 to process the content of one or 
more data streams in a particular manner desired by a user. 15 
By way of example, an application running within the 
system environment operated by information provider #2 
may require data that is derived through computation or 
manipulation from data streams B 3 and Cj produced by 
corresponding applications running within the system envi- 20 
ronment operated by information provider #1. The data 
exchange engine 62 operates on data streams B x and C a in 
the manner dictated by user-specified business logic stored 
in the business logic module 68. 

In contrast to a custom interface implemented in accor- 2 5 
dance with a prior art approach, the data exchange archi- 
tecture illustrated in FIG. 6 and in other Figures provides a 
system administrator or end-user the ability to modify 
routing logic, business logic, or the format of a given data 
stream/application without requiring any modification to 30 
programs or configurations within the data exchange engine 
62. By way of example, if an application or format of a 
particular data stream requires modification, such a change 
may be accomplished in the data exchange architecture by 
simply modifying the interface logic of the implicated 35 
adapter. If, by way of further example, a particular data 
stream produced by information provider #1 is required by 
two, rather than one, application within the information 
provider #2 systems environment, a simple change to the 
routing logic 66 and the addition of another adapter may be 40 
effected to satisfy this additional need. Further, if new or 
additional processing is required for a particular data stream 
in order to satisfy a new need by either a source or 
destination application, a simple change to the business 
logic 68 will satisfy this additional need. 45 

It will be appreciated by the skilled artisan that the 
cooperation between easily modifiable adapters and one or 
more data exchange engines having user-modifiable routing 
and business logic provides for enhanced scalability, 
expandability, and flexibility to meet current and future 50 
information exchange requirements. In contrast to conven- 
tional interfacing schemes, a data exchange architecture 
implemented in accordance with the present invention is not 
subject to obsolescence, primarily due to its inherent ability 
to readily accommodate new and unforeseen applications, 55 
platform technologies, data types and formats, and logic and 
routing requirements. 

A more detailed description of various aspects of an 
adapter in accordance with one embodiment of the present 
invention will now be described with reference to FIGS. 7 60 
and 10. In FIG. 7, there is shown a number of systems, 
Sj-Sy, which may or may not be similar in terms of platform 
configuration. Each of the systems, Sj-S^ implements one 
or more applications, Aj-A^, that produce various types of 
data, denoted as D^D^. As was discussed previously, each 65 
of the data types has an associated informational content 
component and format component, such as informational 
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content component I 2 and format component V 1 associated 
with data type D r 

Each of the adapters 150, 170, 190 include an interface 
module 152, 172, 192 and an object converter 154, 174, 194, 
respectively. As is shown in FIG. 10, data of type D a 
produced by application A 1( for example, is received 280 by 
the interface module 152 of adapter 150. The interface 
module 152 typically includes a validation module which 
validates the type D x data received from application A x . The 
object converter 154 converts 282 the informational content 
component Ij of the type D 1 data to a Common Object data 
structure, C0 2 . Reference information, which may be 
viewed as control or identification information, associated 
with the Common Object or Objects is placed 284 onto an 
input queue of the data exchange engine 132. 

The data exchange engine 132 processes and/or manipu- 
lates 286 the informational content \ x of the type Dj in a 
manner required by the business logic module 136. Routing 
logic 134 is used by the data exchange engine 132 to place 
290 the processed informational content Ij on one or more 
selected output queues (not shown). One or more adapters 
(not shown) having a structure equivalent to adapter 150 and 
individually configured for specified destination applica- 
tions convert 290 the informational content Ij from the 
common format to a specified output format for transmission 
294 to one or more destination applications. 

FIGS. 8, 9, and 11 provide additional details of various 
data exchange operations associated with one embodiment 
of the present invention. Initially, an adapter, such as adapter 
208, receives 300 an externally generated message from an 
application, such as an Operation Support System (OSS) 
application, of a destination service provider. The adapter 
208 receives 302 the message generated by the OSS. The 
application interface 208a of the adapter 208 receives the 
OSS message and data associated with the OSS message 
transmitted from the OSS. The OSS message and/or asso- 
ciated data is validated and converted 304 to a Common 
Object representation by the validater/converter 2086 of the 
adapter 208. The API 208c of the adapter 208 represents an 
application programmer's interface that allows Common 
Objects to be readily constructed, manipulated, and 
enqueued. After the request has been converted into Com- 
mon Object form, the adapter 208 invokes 306 an enqueue 
interface 208c/ to place the OSS message into the receive 
queue 240 of the data exchange engine 202. The informa- 
tional content component or raw data associated with the 
OSS message is transferred to the data store 201 coupled to 
the data exchange engine 202. 

A processing thread received from a processing thread 
pool 262 from the gateway core 204 is implemented 310 to 
dequeue any incoming requests by relative priority. The API 
for the custom-specific rule code is then invoked 312 to 
process the incoming request in compliance with customer- 
specific business rules received from the rules module 232. 
After the business rules have been applied, requests to one 
or more destination OSS applications are then routed 316 to 
a corresponding send queue 242, 244, 246 for delivery. An 
adapter, such as adapter 218, associated with a specific 
destination OSS may then invoke a corresponding dequeue 
API 318 associated with its corresponding send queue 244. 
The API 2186 and converter 218c cooperate to convert 320 
the requested information represented in Common Object 
form to a format and structure specified by the particular 
OSS. The converted data is then transmitted from the 
application interface 218c/ of the adapter 218 to its corre- 
sponding OSS. 

FIGS. 12-14 provide additional processing details con- 
cerning the transport of data through employment of a data 
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exchange infrastructure in accordance with an embodiment provide a thread of control for the custom logic portions of 

of the present invention. As is shown in FIG. 12, a packet of the system. This thread will contro ^ ° f 

data is received 332 from an external source. The received requests, the invocation .of the nile/ro uting and the 

removed or deleted 340 for I^J^"^ 9 Ta statistic monitor module 264 

If the data from the external source is determined tc .be valid ^ ^ statistics log 276 which are used to 

336, a data exchange transaction is then initiated 342. monitoring ^ tracking Q f data as it moves through 

The data received from the external source is then packed 10 ^ data excna nge system. The statistics monitor module 264 

344 into a Common Object in accordance with meta-data ^ prov ides historical performance information on queues 

rules and identified using a unique name or tag. The Com- anc j historical information on system resource usage. As will 

mon Object is then enqueued 346 on the incoming queue of t, e described in greater detail hereinbelow, the statistics 

the data exchange engine. The data exchange transaction is monitor module 264 provides a means for logging and 

then committed. If the transaction is not successful 350, a 15 tracing a given application. Logging reveals the state of the 

rollback of the transaction is then initiated 352. If the application at the time of an error, while tracing provides a 

transaction is successful 350, the data packet from the description of all software events as they occur. The tracing 

external data source is then removed or deleted 354. The information may be used for tracking the application, state, 

above-described process is then repeated for subsequent data anc j otner re i a ted operations. The tracing information may be 

packets received from the external source 332. 20 use d in conjunction with the logging information to deter- 

Referring now to FIG. 13, additional details concerning a mine the cause for an error since it provides information 

data exchange transaction will now be described. When a about the sequence of events prior to an error, 

data exchange transaction is initiated 362, a prioritization FIGS. 15-20 illustrate various aspects of one embodiment 

scheme is employed to dequeue 364 the next Common 0 f a data exchange infrastructure implemented in an object 

Object from the incoming queue of the data exchange oriented program environment. It is to be understood that the 

engine. During the dequeue operation, the custom rule/route foregoing description represents one of many possible 

API associated with the Common Object is called 366. If the approaches to implementing a data exchange architecture in 

custom rules are successfully applied 368, another data accordance with the principles of the present invention, and 

exchange transaction is initiated 362. If the custom rules that other hardware and software implementations may 

cannot be applied successfully 368, the data exchange alternatively be employed, such as an implementation using 

engine 370 determines the default routing of the Common structured programming techniques. 

Object from the configuration routing table. The architecture for implementing the data exchange 

If the routing has not been previously denned 372, the infrastructure in accordance with this embodiment is 

Common Object is enqueued 374 on an error queue. If 35 intended to provide a series of modular building blocks that 

routing has been previously defined 372, the Common may be used in varying combinations to implement a wide 

Object, or a clone of the Common Object if more than one range of information exchange solutions. Each of the blocks 

enqueue operation is applicable, is enqueued on every described below is intended to provide an abstract level of 

outgoing queue identified in the routing table. The data functionality, where the underlying components and their 

exchange transaction is then committed 378 and if success- ^ specific implementation are transparent to the user, such as 

ful 380, the associated data packet is removed or deleted 384 developers and administrators. 

from the external data source. If the data exchange transac- The basic architecture described hereinbelow provides a 
tion is not successful 380, roll-back of the transaction is que ue interface, basic system infrastructure, and stub API 
initiated 382. A subsequent data exchange transaction 362 is hooks that allow implementation of customer specific code, 
then initiated. 45 The blocks described within this architecture may be orga- 
Additional steps associated with Common Object nized as a single or separate executables. All modules within 
dequeueing are shown in FIG. 14. Assuming that a data the context of this embodiment are intended to be corn- 
exchange transaction has been initiated 392, the data pletely modular. 

exchange engine dequeues 394 the next priority Common As was briefly described previously, all requests pro- 
Object from a configured outgoing queue. The data associ- 5 o cessed within this architecture are converted into a Common 
ated with the Common Object in the outgoing queue is then Object format that provides for a generic construction and 
validated 396 and packed into a specified structure having a behavior for all requests. All request and request field 
format and name appropriate for the outgoing or destination naming is externally defined in a meta-data store which 
external data source. If the data validation process is not provides for data definition and/or processing behavior 
successful 398, then the data is deemed corrupt and the 55 changes without modification of the data exchange engine 
Common Object is enqueued 400 on the error queue. If the code. 

data is valid 398, the external data packet is transmitted 402 The basic architecture configuration is intended to provide 

to the outgoing or destination external data source. The data f or a highly scaleable system. All gateway operations can 

exchange transaction is then committed 404 and if deemed run multiple distributed instances since, in this embodiment, 

successful 406, a subsequent data exchange transaction is 60 the only shared resource is the request queuing mechanism, 

initiated 392. If unsuccessful, the transaction is subject to System resource allocations may be controlled by an exter- 

rollback 408 by the engine exchange. nal configuration file and may be dynamically configurable. 

Referring once again to FIG. 9, a processing thread pool The various alterable resources include number of process- 

262 stores a number of processing threads which are selec- ing threads, system and message timeout thresholds, and 

lively implemented when performing dequeue operations. 65 audit trail and message logging levels. All extensions to 

The processing thread pool 262 represents a pool of threads business logic may be implemented in customer specific 

whose number is externally controlled. Its function is to code that is invoked through a stub API. 
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As was described previously, one function performed by 
an adapter is to disassociate the informational content of a 
particular data stream from its associated format, protocol, 
and/or structure. The adapter then transforms the informa- 
tional content into a Common Object form which represents 
a generic format used for containing all information trans- 
ported through and processed by the data exchange engine. 
FIG. 15 is a depiction of one embodiment of a Common 
Object represented graphically as an object containment 
tree. 

A Common Object within the context of this illustrative 
embodiment represents a C++ container object that is used 
to contain multiple portions of attribute data within a single 
flexible object. A Common Object comprises two lists, a 
Private List and a Public List. Both lists contain one or more 
attribute/value pairs (AV pairs). These AV pairs represent 
objects referred to as Common Attribute Objects, each of 
which comprises an attribute name, value, and type. Com- 
mon Attribute classes are available for all of the basic types 
plus some complex types as well. 

The Public List represents a sequence of two types of 
user-defined attributes, which are instances of an Attribute 
class or a Common Object. The Private List contains 
attributes that are used internally by the system for a variety 
of purposes, such as naming, routing, and identifying ances- 
try information. The Public List contains data that the user 
has defined, which may include other Common Objects. 
Each list may contain two types of attributes, type specific 
AV pairs or objects. Contained objects may either be List 
Objects or other Common Objects. The Private List does not 
include contained objects since this list is only used for 
simple tags or header information. 

The following illustrative examples are intended to dem- 
onstrate the behavior of attributes within the Common 
Object. A type specific attribute within a Common Object 
named "Employee" might be of type String with an attribute 
name of "Name" and a value of "John Doe." A List Object 
is typically used to represent multi-value attributes, where a 
single attribute name can represent multiple values or mul- 4Q 
tiple Common Objects. For example, a List Object may be 
used within a Common Object named Department. The 
"Employees" attribute may constitute a list Object contain- 
ing numerous "Employee" Common Objects. 

As can be seen in the illustration of a Common Object 45 
shown in FIG. 15, each node in the containment tree 
represents an attribute identified by its name. The Distin- 
guished Name of an attribute represents the containment 
path from the root node to the node represented by the 
attribute. In accordance with this scheme, it is mandatory 50 
that each attribute have a unique Distinguished Name within 
the object containment tree. By way of example, a Common 
Object named "foo" may have an attribute name "bar." The 
Distinguished Name for this attribute is thus "foo .bar." If a 
second attribute were added, it would require a unique name 55 
such as "barl" and would be addressed as "foo.barl." This 
unique naming requirement is automatically enforced by the 
Common Object. 

The Common Object provides the ability to access 
attributes that are contained in both the Private List and the 
Public List. The Private List attributes are developer or 
system defined attributes used as tags that allow the encod- 
ing of information that is used in later processing of the 
object. The Private List attributes are generally not seen by 
the user since they are developer defined and not user 65 
defined. The Public list is used to contain all user-defined 
attributes, meaning those that specify what the data looks 



like and how it is named. All logic developed to process data 
through the data exchange environment is based on the 
attributes and their values contained in the Public List. 

The Common Base Class is an abstract base from which 
the Common Object Class is derived. An inheritance tree 
graphically depicting the Common Base Class is shown in 
FIG. 17, The main purpose of this class is to provide a single 
object naming and typing mechanism to aid in object tree 
searches and traversals. The Common Base Class is char- 
acterized in the following code -level example. 

EXAMPLE #1 



class: DX_CommonBase : public RWCollectable 



{ 



RWDECLARE_COLLECTABLE(DX_Commo nBase); 
protected: 



public 



char* Name; 
int Type; 

void SctNainc(const char* inNamc); 



}; 



char* GetNameO { return name; } 

int GetTypeO { return type; } 

virtual void PrintContentsO**; 

char* GctType Name (int type); 



The following constant types are used within the data 
exchange environment and may be defined and located in a 
header file named "DX 13 Defc.h". 



EXAMPLE #2 



35 



enum EclassTypes 
{ 



}; 



DX_OBJECT - 0, 

DX_ATTRIBUTE, 

DX_LIST, 

DX_MUL3T VALUE, 

D5L-INTEGER, 

DX_STRING, 

DX_STRINGVAL ) 

DX_DATE f 

DX__TIME, 

DX_REAL, 

DX_BLOB, 

DX BLOB VALUE, 

DX_ VERSION, 
DX_OID_CLASS 



enum EreturnCodes 



{ 



• 0, 



60 



NOT_FOUND « 
SUCCESS, 
FAILED, 
TIME_OUT, 
ACCESSED ENI ED, 
DUPLICATE_OBJECT, 
NO_OBJECT, 
NO_ ATTRIBUTE, 
I NVALI D_ATTRVAL, 
INVALID_ARGS, 
INVALlD_OPERATTON, 
SYSTEM_ERROR 



enum EstorageTypes 
{ 

FLATFTLE = 0, 
DATABASE 

}; 

enum ElistType 
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static const int MAX_PID_XEN=12; 

-continued static const int MAX_JJNE_SIZE=100; 

Various Common Object access methods have been 

* public - o, developed to provide the ability to access attributes con- 

private ' 5 tained within the Common Object. Several of these methods 

}; involve Boolean operations, thus producing either a pass 

" (i.e., true) or a fail (i.e., false) result. Any specific failures are 

static const int MAX__NAME_LEN-255; logged within the called method. Any application specific 

static const int MAX_DOTTED_NAMELEN=8096; error handling that depends on a called method should be 

static const int MAX_MULTI_VAL=255; added by the application developer. The Common Object is 

static const int MAX_BLOB_SIZE=204S; characterized in the following code-level example, 
static const int OID_LEN=128; 

static const int MAX_FILE_NAME=256; EXAMPLE #3 



class: DX_CommonObject: public DX_CommonBase 

^ RWDECI^ARE_COLLECTABLE(DX CommonObject); 

friend class DX_UstObject; 

friend class DX_FileSubQueue; 
public: 

virtual DX_Commo nObj ectO ; 
// Constructors 

//tf name==NULL, the name is set to 1 *NOT_SET'. 

//tf name is ""or contains a V it will be set to "INVALID^ ^ A ^*^ Mm ^ m ^ 



*************************************************/ 



DX_CommonObject(const char* name=0); 



r 



******************************** *****/ 



7 



//Create a copy of an entire DX_CommonObject, 
//but with it's own unique ODD value 

,..„..... ************** ******** ************ 

DX_CommonObject* CloneO, 

1*****************************************************************1 

//All AddAttribute and AddPvtAttribute methods take ownership of 

//the pointers passed in to them. Do NOT delete the pointers after 

//a call to AddAttribute and AddPvtAttribute. The pointers will be 

//deleted when the container DX_CommonObject or DX_LUtObject is deleted. 

//NOTE: When using the following two methods for creating a DX — STRING 
attribute 

// AddAttribute(const char* name, const int type, const void* value) 

// and AddPvtAttribute(const char* name, const int type, const void* value) 

// the value is defaulted to be of type const char* and not UNICHAR* 
// Misuse will lead to unexpected behavior. 

I** **************************************** ****** *********** ******/ 

EreturnCodcs AddAttributepX_CommonAttribute* newAUr); 
EreturnCodes AddAltributepX_ListObject* newAttr); 
EreturnCodes AddAttribute(DX_CommonObject* newAttr); 
EreturnCodes AddAttributefconst char* name, const int type, const void* value); 
EreturnCodes AddPvtAttribute(DX_CommonAttribute* newAttr); 
EreturnCodes AddPvtAttribute(DX_ListObjcct* newAttr); 
EreturnCodes AddPvtAttribute(DX_CommonObject* newAttr); 
EreturnCodes AddPvtAttributefconst char* name, const int type, const void* 
value); 

I*** ******************************************** ************ ******} 

//DeleteAttribute and DclctePvtAttribute will remove the named attribute 

//from the container DX_CommonObject or DX_ListObject and delete the named 

//attribute's pointer 

r ****************************** ****** ***********/ 

EreturnCodes DeleteAttribute(const char* name); 
EreturnCodes DeletePvtAttribute(const char* name); 

/••••" * V 

//Remove Attribute will remove the named attribute from the container 
//DX_CommonObject or DX__UstObject but will not delete the named 
//attribute's pointer 

r * ************************* **************************************/ 

EreturnCodes RemoveAttributefconst char* name); 
EreturnCodes Remove PvtAttribute(const char* name); 

/****" * *********** —/ 

//Do NOT delete the pointer that is returned to you, it still is owned by 
//the container DX_CommonObject or DX_UstObjcct. You CAN use the any of 
//the attribute class methods for the pointer. 



f ***.** 



********* 



** *** 
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void* Gel Attribute (const char* name); 
void* GetPvtAttribute(const char* name); 
void PrintContcntsO; 

//The caller of De marshal is responsible for object's memory allocation 

static DX_CommonObjcci" Demarshalfchar* ObjOid, int type, int Contextlndex); 

Ereturn Codes Marshal(int type, int Contextlndex); 

static EretumCodes DeleteStorage(const char* oid W, int type, int Contextlndex); 

//The caller of GetOID is responsible for deleting the memory of the returned 
char* 

char* GctOIDO; 

EPriorityCode GetPriorityO; 
protected: 

void* Findfconst char* name); 

static EretumCodes Restore PersistentObject(const char* oidVal); 
static EretumCodes Delete PersistcntObject(const char* oidVal, int type); 
private: 

//Data Members 

DX_ListObject* Privatelist; 

DX_ListObject* PublicList; 

static void Delctc(RWDlistCollectables* list); 

static int CopyCRWDlistCollectables* dest, const RWDlistCotlectables *src); 

static EretumCodes CopyPersistentObject(char* filename); 

static EretumCodes CopyFile(char* filename,char* copyfilename); 

void saveGuts(RWFile& file) const; 

void 5aveGuts(RWvostream& stream) const; 

void restoreGuts(RWFUe& file); 

void restoreGuts(RWvistream& stream); 

const int checkO const; 

DX_3oolean update listOids(DX_ListObject* PList, DX_OID *Poid); 

DX_Boolean updateObjcctOids(DX_CommonObject* Pobj, DX_OtD *Poid); 

DX_Boolean ValidateNaming(const char* name); 
#if de fDX__D ATABAS E 

EretumCodes InsertIntoTable(char* filename, int Contextlndex); 

static EretumCodes Retrieve FromTable(char* filename, char* oid, int 
Contextlndex); 

EretumCodes UpdateTable(char* filename, int Contextlndex); 
#endif 

//use to cal. the number of bytes needed to store an object using RWFile 
RWspace binaryStoreSizeQ const;}; 



The following methods are implicated when accessing the 
Public List: AddAttribute; GetAttribute; DeleteAttribute, 
and Remove Attribute. The following methods are impli- 40 
cated when accessing the Private List: AddPvt Attribute; 
GetPvtAttribute; DeletePvtAttribute, and Remove Attribute. 
The AddAttribute, DeleteAttribute, and RemoveAttribute 
methods for manipulating a Common Object are character- 
ized in greater detail in the following code-level examples: 45 

EXAMPLE #4 

AddAttribute: Adds attribute to CommonObject tree 
EretumCodes AddAttribute(DX_CommonAttribute* 

newAttr); 50 
EretumCodes AddAltribute(DX_ListObject* newAttr); 
EretumCodes AddAttribute(DX_CommonObject* 

newAttr); 

EretumCodes AddAttribute(const char* name, const int 
type, const void* value); 55 

EretumCodes AddPvtAttribute(DX_CommonAttribute* 
newAttr); 

EretumCodes AddPvtAttribute(DX_ListObject* 
newAttr); 

EretumCodes AddPvtAttribute(DX_CommonObject* 60 
newAttr); 

retumCodes AddPvtAttribute(const char* name, const int 
type, const void* value); 

EXAMPLE #5 

to 

DeleteAttribute: Removes attribute from CommonObject 
tree and destroys attribute 



EretumCodes DeleteAttribute(const char* name); 
EretumCodes DeletePvtAttribute(const char* name); 

EXAMPLE #6 

RemoveAttribute: Removes attribute from CommonObject 
tree 

EretumCodes RemoveAttribute(const char* name); 

EretumCodes RemovePvtAttribute(const char* name); 

The following Common Object retrieval methods are used 
internally by the GetAttribute Value( ) and 
SetAttributeValue( ) methods to search the attribute list of a 
Common Object and to locate a specific Common Attribute 
instance. These retrieval methods may be used by applica- 
tion developers as well. Each of these methods require a 
fully dot(.) delimited Distinguished Name and will recur- 
sively walk all relative levels of nesting to retrieve the 
relevant object/attribute. 

EXAMPLE #7 

void* GetAttribute(const char* name); 
where, GetAttribute returns a pointer to a Common Attribute 
derived object or Common Object stored within a Common 
Object's Public List. 

EXAMPLE #8 

void* GetPvtAttribute(const char* name); 
where, GetPvtAttribute returns a pointer to a Common 
Attribute derived object from within a Common Object's 
Private List. 
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The following Common Object methods require that the 
attribute name be represented in its dot(.) delimited fully 
distinguished name. This naming convention should be 
followed at all levels of object nesting starting from the 
name of the object instance from which the method is 5 
invoked. These methods also require the user to provide and 
manage memory allocation for attribute values. Additional 
usage examples are given as follows: 



EXAMPLE #9 



10 



EreturnCodes AddAttribute(DX_CommonAttribute* 
newAttr); 

EreturnCodes AddAttribute{DX_ListObject* newAttr); 
EreturnCodes AddAttribute(DX_CommonObject* 15 
newAttr); 

EreturnCodes AddAttribute(const char* name, const int 

type, const void* value); 
EreturnCodes AddPvtAttribute(DX_CommonAttribute* ^ 

newAttr); 

EreturnCodes AddPvtAttribute(DX_ListObject* 
newAttr); 

EreturnCodes AddPvtAttribute(DX_CommonObject* 
newAttr); 25 

EreturnCodes AddPvtAttribute(const char* name, const 
int type, const void* value); 

EreturnCodes Delete At tribute(const char* name); 

EreturnCodes DeletePvtAttribute(const char* name); 

EreturnCodes RemoveAttribute(const char* name); 

EreturnCodes RemovePvtAttribute(const char* name); 

Further examples of AddAttribute and AddPvtAttribute 
method usage are provided as follows: 

35 

EXAMPLE #10 
i int *xx-new int(321); 

if (PtestObj->AddPvtAttribute( < TestObject.PvtIntAttr", 
DX„INTEGER, (void*)xx)==SUCCESS) ^ 

{.--} 
delete xx; 

A further example of GetAttribute method usage is pro- 
vided as follows: 



30 
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A further example of GetAttribute Value method usage is 
provided as follows: 

EXAMPLE #12 



struct DX_AUributc Value tmpAttrVfel; 

if (PtestObj-^etAttributeV^lueCTestObjecLlntAttr", tmpAttrVal) « 
SUCCESS) 



{ 



} 



EXAMPLE #11 

DX_XXX*PtrAttr-objInstance->GetAttribute 

("commonObjName.attrName"); 
DX_XXX*PtrAttr=objInstance->Get Attribute 

("commonObjName.listObjName .attrName"); 



45 



int* newlnt - (int*)tmpAttrVal. value; 

if (ncwlnt) 

{ 

//do something 
delete newlnl; 

} 



A further example of SetAttribute Value method usage is 
provided as follows: 

EXAMPLE #13 
int* newVal-new int(555); 

if (PtestObj->SetAttributeValueC'TestObject.IntAttr", 
(void*)newVal)==SUCCESS) 

{...} 

if (newVal) 
delete newVal; 

In general, each Common Object is given a unique Object 
Identifier or OID so that any child or related objects can be 
associated with each other. All objects created as a result of 
this original OID require that this initial OID be stored as 
part of the object, regardless of whether the new object is a 
direct child object or whether the original object still exists. 
If the original OID were not stored, it would not be possible 
to correlate response objects with the initial request object. 
The OID value is automatically set during instantiation. 
Parent OID values are updated automatically when 
AddAttribute( ) is invoked, including all Common Objects 
that are contained within a ListObject. 

The OID is typically a concatenation of count, pid, time, 
hash, and hostid in order to guarantee its uniqueness. An 
illustrative example is provided as follows: 

EXAMPLE #14 



class: DX_OID: public DX_Comrnon Attribute 

^ RWDECLARE_COLLECTABLE(DX_OID); 

friend class DX_Sy5ConfigObject; 

friend class DX_CommonObject; 

friend class DX_UstObject; 
protected: 

DX_OID(chai* value); 

DX_OlD(const char* name, char* value); 
public: 

// constructors 

dx_oid(); 

virtuaKDX_OID0; 



// Get a copy of type specific value. User should new a pointer for the 
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-continued 



// return value and then delete the pointer after use 

Ercturn Codes GetAttribute Vahie(void * value); 
Ere turn Codes GetAttribute Value(char* value); 
void PrintContcntsO; 
private: 

static unsigned long OlDCOUNP, 
#ifndef 11PUX 

static DX_Mutex lockOidCount; 
#cndif 

char •Attr'Value; 

char •storeFUeName; 

char *5loreDirName; 

void saveGuts(RWFile& file) const; 

void saveGuts(RWvostream& stream) const; 

void restoreGuts(RWFUe& file); 

void restoreGuts(RWvistream& stream); 

EretumCodes SetAttribute\&lue(void• value); 

char* GetDirNameO; 

char* GetFileNameO; 

static DX^Boolean CheckO[DFonnat(char* oid\fcl); 



The use of reference counting greatly reduces the amount 
of time and memory that is required to copy objects. Use of 
a third-party foundation class library, such as one developed 
by Rogue Wave Software, Inc., automatically supplies a 
number of the copy constructors. Also, methods within the 
DX_CommonObject class itself make use of the Rogue 
Wave copy methods as well. It is noted that the 
DX_StringAttribute and DX_BlobAttribute classes pro- 
vide their own copy optimization through reference 
counting, as objects of these classes could be of a substantial 
size. 

The Common Attribute is an object that is contained 
within a Common Object and is used to contain attribute 
data. The Common Attribute contains a private attribute that 
denotes the specific attribute type and a set of public 
attributes for name and value. A Common Attribute may be 
a simple attribute of a specific data type, name, and value or 
it may contain another object, such as a List Object or 
Common Object. The type specific Common Attribute 
classes all inherit their capabilities from the generic Com- 
mon Attribute class so all classes will behave in an equiva- 
lent manner. Reference is made to FIGS. 16A-16D, which 
illustrate the contents of a Common Attribute when used to 
represent some of the supported data types. 

The Common Attribute class is an abstract base class from 
which type specific Attribute classes are derived, a charac- 
terizing example of which is given as follows: 

EXAMPLE #15 



class: DX_CommonAtiiibute : public DX_CommonBase 
{ 

public: 

virtual EretumCodes GetAttribute Value( void* value) = 0; 
virtual EretumCodes SctAttributeVarue(void* value) - 0; 
virtual void PrintContentsO=0; 

}; 



The following attribute value access and modification 
methods, termed GetAttributeValue and SetAttribute Value, 
are intended to provide access to the attribute value. It is 
noted that the caller is responsible for the memory allocated 
in the storage type. Two usage examples are provided as 
follows: 

EXAMPLE #16 

DX_CommonAttribute* Pattr^O; 
Pattr=(DX_CommonAttribute*)PrestoredObj- 
>GetAttribute 

("TestObject.ListObject.IntAttrInList3 ,, ); 
int* intVal-new int; 

if (PmyOID && PmyOID->GetAttributeValue(intVal) 

!=SUCCESS) { . . . } 
if (intVal) 
delete inVal; 

EXAMPLE #17 
int* newVal=new int(555); 

if (PtestObj->SetAttributeValue("TestObject.IntAttr", 
(void*)newVal)==SUCCESS) { . . . } 

if (newVal) 

delete newVal; 
In one embodiment, a set of overloaded operators are 
provided for performing attribute value comparison opera- 
tions. In another embodiment, the following comparison 
operators are supported for Attributes: or equal opera- 
tor; "!-" or not equal operator, ">" or greater than operator; 
and "<" or less than operator. 

The following non-exhaustive list of attribute types sup- 
ported by the Common Attribute are given as follows: 
Integer; String; Date; Time; Real; Blob; Version, 
MultiValue, ListObject, and ListObjectlterator. It is noted 
60 that the MultiValue attribute type represents a container 
attribute that may have multiple values, and that the ListO- 
bject attribute type typically contains a number of attributes 
or objects to represent a multi-valued attribute. It is further 
noted that Object version control is implemented by using a 
65 private Version object attribute. Any changes to object or 
attribute makeup will be converted transparently when any 
new version is introduced. 
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Code-level examples of various type specific attribute EXAMPLE #18 

classes that are supported are provided as follows: 



attribute class: DX_IntegerAttribute 

r " * * 

* CLASS NAME : DX_lntegerAttribute 

* INHERITED FROM None 

* INHERITS DX„Co mm on Attribute 

* DESCRIPTION Provides storage for integer attributes 

* • / 

class DX_IntegerAttribute:public DX_CommonAttribute 

^ RWDECIJVRE_COLLECTABLE(DX_IntegerAttribul£); 

public: 



// If name— NULL, the name is set to "NOT_SET\ 

// If name is M "or contains a it will be set to "INVALID NAME" 

/ * ' 

DX_IntcgerAttribute(const char* namc-0); 
DX_IntegerAttribute(const char' name, tnt value); 
virtual-DK_lntegerAttributeO; 



II The memory for the value argument is allocated and deallocated 
// by the caller. The library function GetAttribute Value just writes 
// to the value argument and the SetAttribute Value just reads the 
// argument to reset the value of the attribute 

/—*•••••••••" * *** / 

EretumCodes GetAttribute Value(void* value);// argument assumed to be tnf 
EretumCodes GetAttribute Value(int& value); 

EretumCodes SetAttribute Value^oid* value);// argument assumed to be inf 
EretumCodes SetAttribute Value(int value); 
void PrintContentsO; 
private: 

int Altr Value; 

void saveGuts(RWFile& file) const; 

void saveGuts(RWvostream& stream) const; 

void restareGuts(RWFdc& fUc); 

void restoreGuts(RWvustream& stream); 

}; 



EXAMPLE #19 



attribute class: DX_StringAttribute 

• CLASS NAME DX_StringAttribute 

• INHERITED FROM None 

• INHERITS DX_CommonAttribute 

• DESCRIPTION : Provides storage of strings. 



class DX_StringAttribute : public DX_Common At tribute 

^ RWDECLARE_COLLECTABLE(DX_Strin S Attribute); 
public: 

// If name==NULL, the name is set to M NOT_SET\ 

// If name is or contains a V it will be set to "INVALID NAME" 

^i.,,,,,... .,*..........«.... •*«*•***•* • 

DX_StringAttribute(consl char* name=0), 
DX_StringAttribute(const char* name, const char* value); 
DX_StrmgAttributc(const char* name, const UNICHAR* value); 
DX_StringAttribute(const char* name, const DX_String& value); 
virtual~DX_StringAttributeO; 
/ * * 

// Get a copy of char* value. The library will allocate the 

// appropriate storage, the user should delete the pointer after use. 

y . 

EretumCodes GetAttribute Value(void * value);// assumes char*" is passed 
// Get a copy of type specific value. The library will allocate the 
// appropriate storage, the user should delete the pointer after use. 

/ — — • * * 

EretumCodes GetAttribute Value(char* &value); 
EretumCodes GetAttribute Value(UNICHAR* &value); 
EretumCodes GetAttributeValue(DX_String* &value); 
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-continued 



/ •/ 

// The memory for the value argument is allocated and deallocated 
//by the caller. The library functions just read the value 
// argument to reset the value of the attribute. 
// NOTE: the method taking (void" value) assumes const char* 
/ " * ' 
EretumCodes SetAttribute\fclue(void* value); 
EreturaCodes SetAUribute\felue(const char* value); 
EretumCodes SetAttribute^value^const UNICHAR* value); 
EretumCodes SetAttributc\alue(const DX_String& value); 
void PrintContentsQ; 
private: 

DX_String* AttrValue; 

void saveGuts(RWFile& file) const; 

void saveGuts(RWvostrcam& stream) const; 

void restoreGuts(RWFile& file); 

void restoreGuts(RWvistream& stream); 



EXAMPLE #20 

class: DX_String 

The DX_Siring class is a reference counted container 
class used by the DX_StringAttribute to store the 25 
attribute's value. It provides the user a way to keep 
down the overhead associated with having to copy the 
data. 



class DX_String : public RWCollectable 

^ RWDECLARE_COLLECTABLE(DX_Stnng) 

friend class DX_StringAttribute; 
public: 

DX_String(); 

DX_String(const char* value); 
virtual~DX_StringO; 
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-continued 



void PrintContcntsO; 
private: 

char* StringValue; 
int* len; 
int* refCount; 

DX_String& opera tor=(const DX__String& rhs); 

void saveGuts(RWFile& file) const; 

void saveGuts(RWvostream& stream) const; 

void restoreGuls(RWFile& file); 

void restoreGuts(RWvistream& stream); 



EXAMPLE #21 



attribute class: DX„DatcAttribute 

/ * " * *** 

* CLASS NAME : DX_DateAttribute 

* INHERITED FROM None 

* INHERITS DX_CommonAttribute 

» DESCRIPTION Provides storage for Date attributes 

* NOTE: This class only stores the date related fields of the struct tm* 

* The time related fields are initialized to 0, any data passed in 

* the 6truct tm* time related fields will be discarded. 
.,**.,....„**....,..*. 

class DX_DateAttribute : public DX_Comrnon Attribute 

^ RWDECLARE_COLLCCTABLE(DX__Date Attribute); 
public: 

,..„..„.„««.„•••..........««.«........»«««...«.-/ 

// If name— NULL, the name is set to "NOT_SET". 

// If name is ""or contains a V it will be set to "INVALID—NAME" 

DX_DateAltribute(const char* name=0); 
DX_DateAttribute(const char* name, const struct tm value); 
virtual DX_DateAttribule(); 

,„..„.....„„.....„„...«....................—...-.../ 

// The struct tm passed as an argument for GetAttributeValue 
// is to be allocated and deallocated by the caller 
// The library function just copies the value into the 
// structure. 

EretumCodes GetAttributeVatue(struct tm& value); 

EretumCodes GetAttributeVfelue(void* value); // assumes struct tm* is passed 
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-continued 



// The memory for the value argument is allocated and deallocated 
// by the caller. The library functions just read the value 
// argument to reset the value of the attribute 
,,.„,...........*........ ...... ........................ 

EretumCodes SetAttribute Value(void • value); 
EretumCodes SetAttribute Value(con6t struct tm value); 
void PrintContentsO; 
private: 

RWCollectableDatc *AttrValuc; 

void saveGuts(RWFlle& file) const; 

void saveGuts(RWvostream& stream) const; 

void resloreGuts(RWFile& file); 

void restoreGuts(RWvistream& stream); 



EXAMPLE #22 



attribute class :DX_Timc Attribute 

„„„.„.....„.,.,..........................".-.«".♦ 

** CLASS NAME DX_Time Attribute 

• INHERITED FROM None 

• INHERITS DX_Cb mm ooAt tribute 

• DESCRIPTION Provides storage of time values in form of SSE. 
...I..,*.*..*...****.*..**..******..*.*.*....**.****************/ 
class DX_TimcAttribute : public DX_CommonAttribute 

^ RWIDECLARE_COLLECTABLE(DX„rimeAUribute>, 
public: 

^» *»****..*.«»**»*»»».»»•»»*»**•*** ».***«**»•»****** ******/ 

// if namc==NUUL, the name is set to u NOT_SET\ 

// If name is ""or contains a V it will be set to "INVALID_NAME" 

.................................. ........... 

DX_TlmeAttribute(const char"name=0); 
DX_TimeAttribute(const char* name, unsigned long value); 
viitual~DX_TimeAttributeO; 



'*/ 



// The memory for the value argument is allocated and deallocated 
// by the caller. The library function GetAttribute Value just writes 
// to the value argument and the SetAttribute Value just reads the 
// argument to reset the value of the attribute 
/ „„. .„.,.,,....................»..*.... .............. 

// argument assumed to be unsigned long* 
EretumCodes GetAttribute Value(void* value); 
EretumCodes GetAttribute Value(unsigned long& secondSinoeEpoch); 
// argument assumed to be unsigned long* 
EretumCodes SetAttribute Valuefvoid* value); 
EretumCodes SetAttribute Value(const unsigned long value); 
void PrintContentsO; 
private : 

RWCollectableTime* AttrValue; 

void saveGuts(RWFile& file) const; 

void saveGuts(RWvostrcam& stream) const; 

void restoreGu[s(RWFile& file); 

void restoreGuts(RWvistream& stream); 

}; 



v 



EXAMPLE #23 



attribute class :DX_RealAttribute 



........... ........... 

* CLASS NAME 

• INHERITED FROM 

* INHERITS 

• DESCRIPTION 



DX_RealAttribute 
None 

DX_CommonAttribute 
Provides storage of float types 



7 



class DX_RealAttribute : public DX_CornmonAttribute 
{ 
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-continued 

RWD EC I^RE_COLLECTABLE(DX_Real Attribute); 

public: 

//If came=«NULL, the name is set to "NOT_SET\ 
//If name is ""or contains a *\" it will be set to 
//"I NVALID_N AM E" 

/— * f 
DX_RealAttribute(const char* rtame-0); 
DX_RealAttribute(const char* name, float value); 
virtual ~DX_RealAttribute( ); 

.......................... .............. ........./ 

//The memory for the value argument is allocated and 
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-continued 



-continued 



//deallocated by the caller. The library function 
//GetAttribute Value just writes to the value argument 
//and the SetAttributc Value just reads the argument 
//to reset the value of the attribute 

.......................... ............... 

Ere turn Codes GetAttribute Value(void* value); //argument 
assumed to be 

r 

EreturnCodes GetAttribute Value(float& value); 
EreturnCodes SetAttribute\klue(void* value); //argument 
assumed to be 



float* 



size); 

unsigned int GetBlobSize( ); 
void PrintContents( ); 
private: 

DX_Blob* Attr Value; 
void saveGuts(RWFile& file) const; 
void saveGuts(RWvostream& stream) const; 
void restoreGuts(RWFile& file); 
void restareGuts(RWvistream& stream); 



20 



float* 

EreturnCodes SetAltribute Value (float value); 
void PrintContents( ); 
private: 

float AttrValue; 

void saveGuts(RWFUe& file) const; 

void saveGuts(RWvostream& stream) const; 

void restoreGuts(RWFile& file); 

void restoreGuts(RWvistream& stream); 



EXAMPLE #24 



attribute class :DX_B lob Attribute 

/ * *** ........ 

* CLASS NAME : DX_BlobAttribute 30 

* IN HER [TED FROM : None 

■ INHERITS : DX_CommonAttribute 

* DESCRIPTION : Attribute storage class to store raw 

* binary stream 

* stored in a unsigned char* 
Takes/returns DX_Blob struct 35 

class DX_Blob Attribute : public DX_CommonAttribute 

^ RWDECLARE_COLLECTABLE(DX_Blob Attribute); 
public: 

....p...*...**,,,.. ............... ........ 

//If name==NULL ) the name is set to "NOT__SET". 
//If name is or contains a ".'* it will be set to 
It IN VALI D_N AM E" 

— * "* V 

DX_BlobAttribute(const char* name=0); 
DX_B lob Attr ibutefconst char* name, const DX_Blob& value); 
DX_BlobAttribute(const char 4 name, unsigned char* value, 45 
unsigned int size); 
virtual ~DX_BlobAttribute( ); 

//Get a copy of DX_Blob* value. The library will allocate the 
//appropriate storage, the user should delete the pointer after use. 
,...*, •,,...••.*•«..........*.***« ......***..*....., 50 

EreturnCodes GetAttribute Value(void* value) ^/assumes 
DX_Blob** 

.................................................... 

//Get a copy of type specific value. The library will allocate the 
//appropriate storage, the user should delete the pointer after use. 

/" * * — * / 55 
EreturnCodes GetAttributeVa lue(DX_Blob* &value); 
EreturnCodes GetAttributeValue(unsigned char* & value); 

/ ; •/ 

//The memory for the value argument is allocated and 

//deallocated by the caller. The library functions just read 

//the value argument to reset the value of the attribute. ^ 

//NOTE: the method taking (void* value) assumes 
//const DX_Blob* 

/ * * / 

EreturnCodes SetAttributeVdue(void* value); 
EreturnCodes SctAttributeValue(const DX_Blob& value); 
EreturnCodes SetAttribute Value (const unsigned char* value, 65 
unsigned int 



EXAMPLE #25 



class: DX_Blob 

The DX_Blob class is a reference counted container class used 
by the DX_Blob Attribute to store the attribute's value. 
It provides the user a way to keep down the overhead associated 
with having to copy the data. 

class DX_Blob : public RWCollectable 

^ RWDECLARE_COLLECTABLE(DX_Blob); 

friend class DX_BlobAttribute; 

friend class DX_MultiValue Attribute; 
public: 

DX_Blob( ); 

DX_Blob(const unsigned char "value, unsigned int size); 
~DX_Blob( ); 

DX_Blob& operator=(const DX_Blob& rhs); 
void PrintContenls( ); 
unsigned int GetBlobSize( ); 
EreturnCodes GetValue(unsigned char* ' value); 
private: 

int* refCount; 
unsigned int* BlobSize; 
unsigned char* BlobValuc; 
void saveGuts(RWFile& file) const; 
void saveGuts(RWvostream& stream) const; 
void restoreGuts(RVVFile& file); 
void restoreGuts(RWvistream& stream); 



}; 



EXAMPLE #26 



attribute class:DX_VersionAttribute 



/* 



CLASS NAME 
INHERITED FROM 
INHERITS 
DESCRIPTION 



DX_VersionAttribute 
None 

DX_CommonAttribute 
Provides a integer value that 
can be used to mark the version of 
an object in process. 



class DX_VersionAttribute : public DX_CommonAltribute 



RWDECLARE_COLLECTAB LE(DX_ Ve rsionAttribute); 
public: 

................ ...... ...... ................. ■ 

//If name=NULL, the name is set to "NOT_SET". 
//If name is or contains a "." it will be set to 
//"INVALID__NAME" 

................................................ 

DX_VersionAUribute(const char* namc«0); 
DX_VersionAUribule(const char* name, int value); 
virtual -DX_VersionAttribute( ); 
/* 



//The memory for the value argument is allocated and 
//deallocated by the caller. The library function 
//GetAttribute Value just writes to the value argument 
//and the SetAttribute Value just reads the argument 
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32 

EXAMPLE #28 



//lo reset the value of the attribute 
.......... 

EreturaCodes GetAttribute Value(void* value); 
//argument assumed to be int* 
EreturaCodes GetAttribute Varuc(int& value); 
EretuxnCodes SetAttributeVarue(void* value); 
//argument assumed to be int* 
EreturaCodes SelAt tribute Value (int value); 
void PrintContents( ); 
private: 

int Attrvalue; 

void EaveGuts(RWFile& file) const; 

void saveGuts(RWvostream& stream) const; 

void restoreGuts(RWFile& file); 

void restorcGuts(RWvistream& stream); 



10 



class: DX_MultiValStruct 

The DX_Multi\blStruct is a container class used by the 
DX_Multi Value to store the attribute's value. It contains 
the attribute type information, the number of individual attribute 
values and an array of pointers to the attribute value elements, 
struct DX_MultiValStruct 
{ 

int valType; 
int entries; 

voic" val PtrArr[MAX_MULn_ VAL]; 



}; 



EXAMPLE #29 



A MultiValue attribute by definition is a single named 
attribute that contains multiple individual values of the same 
type where the multiple individual values make up the 
attribute's single value. These multiple values are generally 
not individually addressable from the attribute level. 
Examples of a MultiValue attribute and usage of same are 
given in the following examples. 



Instantiation: 

int •intl - new int(l); 
int *int2 = new int(2); 
struct DX_MuItiValStruct tmpStruct; 
if (intl && int2) 
25 { 



EXAMPLE #27 



tmpStrucLvalType - DX_INTEGER; 
tmpStructcn tries = 2; 
tmpStruct valPtrArr[0] = intl; 
tmpStrucLvalPtrArrjl] - int2; 

30 DX_MultiValueAttribute "PmvAttr - 0; 

PmvAttr = new DX_Multi\fclue Attribute 

CMultiValuedAttribute",&tmpStruct); 

,*.»»».*.*»,«.»•*.*.**»*.*«******»*«*«************»****** //cleanup 

if (intl) 

* CLASS NAME : DX_MultiValueAttribute delete intl; 

* INHERITED FROM : None 35 if (int2) 

* INHERITS : DX_CommonAttribute delete int2; 

* DESCRIPTION Provides storage of multiple values 

* for a single attribute instance given 

* that all attribute values MUST be the 

* same type. 

.,,.,...........-..,...........-— — ..-—"—/ 4Q 

class DX_Mu]tiValucAttribute : public DX_CommonAttributc 

^ RWDECLARE_COLLECTABLE(DX_Mul tiValue Attribute); 
public: 

//If name— NULL, the name is set to "NOT_SET". 
//If name is **" or contains a "." it will be set to 
/r IN VALI D_N AM E' ' 

/ • ** / 

DX_Multi Value Attribute(const char* name=G); 
DX_MultiVWueAttribute<const char* name, const struct 
DX_MultiValStruct* 
value); 50 
virtual -DX_Multi Value Attribute ( ); 

...........„.»«........./ 

//Get a copy of type specific value. User should new a 
//pointer for the return value and then delete the 
//pointer after use 

/ 55 

EreturaCodes GetAttribute ValuefpX_MultiValStruct* value); 
EreturaCodes GetAttribute Value(void * value); 
EreturaCodes Se tAt tribute Value(const struct 
DX_MultiValStruct* value); 
EreturaCodes SetAttribute\alue(void* value); 

void PrintContents( ); 6Q 

private: 

RWDlistCollectables* AtxrValue; 
void saveGuts(RWFUe& file) const; 
void saveGuts(RWvostream& stream) const; 
void restoreGuts(RWFile& file); 

void restor C Guts(RWvistr Ca m& stream); 65 ^ ^ discussed prev iously, a List is a sequence Of 

. . — attributes, i.e., instances of attribute classes and/or Common 

Objects, an example of which is given as follows: 



EXAMPLE #30 



GetAttribute Value: 

struct DX_MultiVolStruct "retStruct - new DX_MultiV a lStruct; 
if (retStruct) 

^ if (PmvAttr.>GetAttributc\yue((void*)rctStruct)) 

for (int t-0; i<retStruct->entries; i++) 

int *retlnt - (rat*)retStruct->valPtrArr[i]; 
if (retlnt) 
{ 

//Do stuff 
delete retlnt; 

} 



} 
} 

else 

cerr «"###### GetAtlributeValue FAILED 
for Integers #####*r*'«endl; 
delete retStruct; 



} 
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EXAMPLE #31 



CLASS NAME 
INHERITED FROM 
INHERITS 
DESCRIPTION 



DX_listObjecl 
None 

DX CommonBase 

Provides sequential storage for all 
DX_'Object and DX_*Altribute 
classes. When used with a 
DX_UstObj"ectIterator the list can 
be walked an element at a time 
and perform a recursive operation. 



class DX_UstObject : public DX_Com mo nAt tribute 



RW D ECLARE_COLLECTAB LE(DX_ListObject) ; 
friend class DX_UstObjcctItcrator, 
friend class DX_CommonObject; 
protected: 

//Data Members 

RWDListColJectables* Attrvalue; 
char 'Parent; 

DX_ ListObject(consl char* name, char* parent); 
public: 

//Constructors 
r *..,.„. ...,«,. ......... 

//If name==NULL, the name is set to M NOT__SET". 
I fit name is **' contains a it will be set to 
/riNVAUD„NAME" 

r 



•/ 



DX^ListObjectfcoast char* name-O); 
DX_ListObject(const DX_ListObject& reO; 
virtual ~DX_ListObject( ); 
**#**«**»»**«**»»»»•*»**»»«*»*****»*******»******/ 

//All AddAttribute methods take ownership of the pointers 
//passed in to them. Do NOT delete the pointers after a 
//call to AddAttribute. The pointers will be deleted 
//when the container DX_ListObject is deleted. 
// 

//NOTE: When using the following two methods for creating 
//a DX_STRING 
attribute 



AddAttribute(const char* name, const int type, 

const void* value) and AddPvtAttribute(coiist char* name, 

const int type, const void* value) 

the value is defaulted to be of type const char* 
and not UNICHAR* 

Misuse will lead to unexpected behavior. 



EretumCodes AddAttribute(DX_CommonAltribute* newAttr); 
ErcturnCodes AddAttribute(const char* name, const int type, 
const void" 
value); 

EretumCodes AddAttribute(DX_CommonObject* newObj); 
EretumCodes AddAttribute(DX__ListObjecf newObj); 

//Do NOT delete the pointer that is returned to you, 
//it still is owned by the container DX^ListObject 
//You CAN use the any of the attribute class 
//methods for the pointer. 

DX_CommonBase* GetAttributc(const char* name); 



...... 

//Removes from list, but docs not delete 



EretumCodes RemoveAttribute(const char* name); 
............................. ....... *« 

//Removes from list, and deletes the pointer 
/*"***• 

EretumCodes DeleteAttribute(const char* name); 
DX_CommonBasc* Find{const char* name); 
void PrintContents( ); 
private: 

void eaveGuts(RWFile& file) const; 

void saveGuts(RWvostream& stream) const; 

void restoreGuts(RWFile& file); 



34 

^continued 



void restoreGuts(RWvistream& stream); 



10 



The ListObject iterator enables a user to incrementally 
retrieve and use objects or attributes contained within a 
ListObject, an example of which is given as follows: 



20 



25 



45 



EXAMPLE #32 



CLASS NAME 
INHERITED FROM 
INHERITS 
DESCRIPTION 



«»*««***** 



•*••*****• 



DX_ Lis tObjcctltcr ator 
None 

DX_CommonBase 
Provides sequencial retrieval for all 
DX__*Object and DX_"Attribute 
classes store within a 
DX^ListObject. 



V 



}; 



class DX_^ListObjectIterator : public DX_CommonBase 
{. 

private: 

RWDlistCollectablesIterator 'lisater, 
public: 

DX_ListObjectIterator(const DX_ListObject& PlistObj); 
virtual ~DX_listObjectIterator( ); 
void toFirst( ); 
void toLast( ); 

void* nextf );//returns nil when end of list ia reached 
void* getCurrent( ); 



An example of ListObject usage is provided as follows: 
35 EXAMPLE #33 

Assumes a populated DX_ListObject identified by a pointer 
"PlistObj" 

// Instantiate the DX_ListObjectIterator for 
40 DX__ListObject pointer PlistObj 

DX_ListObjectIterator Plistlter(* PlistObj); 
// Set the iterator to the beginning of the list 
PlistIter.toFirst( ); 

DX_CommonBase * PcurrentObj =0; 
PcurrentObj-(DX_CommonBase*)PlistIter.getCurrent( 

); 

while(PcurrentObj) 

{ 

50 // Do something with object/attribute 

PcurrentObj-(DX_CommonBase*) Plistlter.next( ); 

Having discussed in detail various aspects of the Common 
55 Object design hereinabove, a more comprehensive descrip- 
tion of a data exchange system infrastructure in accordance 
with one embodiment of the present invention is provided 
below. The various aspects of the system infrastructure 
described in greater detail hereinbelow include: configura- 
60 tion management; logging and tracing; context definition; 
performance and statistics monitoring; administration and 
maintenance; security; processing thread pool; internation- 
alization; and process procedures. 

Configuration management involves managing the static 
65 and run time configurable parameters of the various com- 
ponents of the data exchange system. When a component in 
the data exchange system is initiated, it reads a specific text 
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file, referred to as the configuration file (<component_ 
namo.cfg, specified either in directory $(DX_HOME)/ 
DX_Config or current working directory) to determine the 
initial values of the parameters. It is noted that each com- 
ponent has its own configuration file, but multiple instances 5 
of a component share the same file. Default values are 
assumed for parameters not specified in the configuration 
file. If there are multiple entries for a parameter, all entries 
except the first entry are ignored. 

Parameters of a component, such as trace/log settings, 10 
may be changed at run time. For this purpose, configuration 
management tools provide a command line interface and a 
Web interface for viewing and configuring various param- 
eters at run time. It is noted that various components of the 
data exchange system may be running on different machines. 15 
Thus, the configuration management utility provides the 
ability to view and modify the parameters of a component 
running on a different machine, possibly on a different 
platform. The Web interface of the configuration manage- 
ment utility provides the requisite connectivity to a remote 20 
machine and provides the capability for performing remote 
configurations. 

When initiated, a component creates an instance of a 
System Configuration Object (DX_SysConfigObject) that 
stores the current parameter settings. The component also 25 
registers for a Signal/Event so that it is informed of changes 
to the configuration using the dynamic configuration com- 
mand line interface/web interface. When a user wants to 
change the run time parameters of a component (identified 
by the process ID and the machine on which it is running), 30 
a signal/event is sent to the component to update its con- 
figuration. A signal/event handler invokes the 
ReconfigParameters( ) method on the 
DX_SysConfigObject, which takes care of reconfiguring 
the various controller objects, such as DX_TraceLogObject, 35 
DX_QueueManager, and DX„ThreadController for 
example. The System Configuration object, 
DX_SysConfigObject, is a singleton object that initializes 
and controls the configuration of a component in the data 
exchange system, such as logging/tracing levels, thread 40 
controller, queuing, and performance monitoring, A single- 
ton object, as understood in the art, refers to a C++ nomen- 
clature meaning that only a single instance of the class may 
exist within a single executable. A singleton object is most 
commonly used when controlling system wide resources. 45 

Two macros, DX_SYSINIT and DX_SYSEXIT, are 
used to manage initialization and destruction of the 
DX__SysConfigObject, respectively. A usage example of 
these two macros is given as follows: 

50 

EXAMPLE #34 

#deflne DX_SYSINIT(ComponentName) \ 

DX_SysConfigObject::Instance(ComponentName); \ 
RegisterForEvent( ); 55 
#define DX__SYSEXIT EndWaitForEvent( ); \ 
DX__SysConfigObject::DeleteInstance( ); 
class DX_SysConfigObject{ 
public: 

// To ensure that only one instance of the System Config 60 
object 

// exists, one has to always use this function to obtain a 
// reference to the 

// system config object 65 
// Cannot delete the pointer returned, use 
// DX_SYSEXIT if you want to delete 



356 Bl 

36 

// the sysconfigobject 

static DX_SysConfigObject* lnstance(char 

*componentName=0); 
// static method to delete the instance of the singleton 

object 

static void Deletelnstance( ); 

// Called when the parameters are to be changed to run 
time 

void ReconfigParameters( ); 

// used to find parameter values by name from the param- 
ValueList 

// do not delete the pointer returned by this function 
char *FindValue(char *name); 
private: 

// constructor is private to make sure the user cannot 
instantiate 

DX_SysConfigObject(char *componentName); 
// destructor 

-DX_SysConfigObject( ); 

// to read the configuration file and initialize tbe 

// paramValuelist 

EreturnCodes InitParamValueList(char *dx_home, 

char** outCfgFileName); 
void GetTraceLogParams(DX_INDICATOR 

*trcLogCategoryInd, 

char* trcLogDir, 

long &logSize); 
// a pointer that stores the one and only instance of the 
// system config object 
static DX_SysConfigObject* instance; 
// the list of various configuration parameters 
//DX„ListObject *paramValueList; 
RWDlistCollectables *paramValueList; 
char ComponentName[MAX_NAME_LEN]; 
// Pointer to DX_ThreadController instance 
DX_ThreadController *PthrCtrl; 
// Method to instantiate DX_ThreadController 
// after DX_SysConfigObject constructor 
EreturnCodes InitThreadController( ); 
void DeleteThreadController( ); 
void DeletePMonitor( ); 
// Pointer to DX_Monitor instance 
DX_Monitor *pMonitor; 
// Method to instantiate DX_Monitor after 
// DX_SysConfigObject constructor 
EreturnCodes InitMonitor(const char *appName); 
EreturnCodes InitTraceLogObject(char* 

componentName); 
// Get Monitor config parameters 
void GetMonitorParam(struct MonConfigType 

*monConfig); 
// To access the DX_ThreadController object 
DX_ThreadController* GetThreadController( ); 
DX_Mutex* paramListLock; 

The configuration management utility provides a com- 
mand line interface to get/set the run time configurable 
parameters of each component in the data exchange system. 
A Web interface may also be used to provide for component 
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configuration, which would internally be using the com- 
mand line interface. The following commands are provided 
for configuration management. 

The DX_ConfigGet command may be used to view the 
configuration parameters for a particular instance of a com- 
ponent identified by its name and typically running on the 
same machine. A user may choose to specify parameters of 
particular interest. Otherwise, a list of all the parameters is 
returned. The syntax for this command is: 

DX_ConfigGet <component name>[<param name>] 

The DX_ConfigSet command is used to modify config- 
urable parameters for a particular instance of a component at 
run time. The instance is identified by the component name 
and the process ID. The syntax for this command is: 

DX_ConfigSet <component namexprocess idxparam 
name>=<new value>{[<param value>=<new value>]} 

The logging and tracing utility provides for logging and 
tracing during execution of a component. As discussed 
previously, logging reveals the state of the component at the 
time of an error, while tracing provides a description of all 
software events as they occur. The tracing information may 
be used for tracking the component-state, and other related 
operations. It may be used in conjunction with the logging 
information to determine the cause of an error, as it provides 
information about the sequence of events prior to an error. 

A component that intends to record a log/trace message 
indicates the category to which the message belongs. The 
log and trace messages are recorded in two different files 
whose names are derived from the name of the application, 
as indicated in the following example: 

(<componentNamexpid>.log and 
<componentName><pid>.trc, respectively) 

The possible severity levels for logging various diagnostic 
messages are as follows. The CRITICAL severity level 
indicates that the component is in a critical state and cannot 35 
proceed properly until the problem is attended to. The 
MAJOR severity level indicates that a particular activity/ 
operation of the component has failed. However, this may 
not effect other activities that may continue to run. The 
WARNING severity level indicates that the component 40 
acted in an unexpected manner. This may be something 
minor, such as a component receiving an invalid message. 

Tracing involves recording three types of messages, 
which are typically specified by the developer. The INFOR- 
MATION (SYS_INFO and APP_INFO) message provides 45 
a record of specific events that occur during the execution of 
the component, such as beginning of a new control thread. 
SYS_INFO is used within the DX libraries and APP_INFO 
is to be used by applications using the DX libraries. The 
TRACE (SYS_TRACE and APP_TRACE) message pro- 50 
vides a detailed record of various software events that occur 
during the course of normal execution of the component. 
SYS__TRACE is used within the DX libraries and APP_ 
TRACE is to be used by the applications using the DX 
libraries. The AUDIT message provides a record of all the 55 
information sent or received by various components of the 
data exchange system. 

A configuration file is used to store trace/log related 
parameters in one or more directories. The TRACE__LOG_ 
DIR directory is used to store the trace/log files. If this 60 
parameter is not specified, it is set by default to the current 
working directory. The tracing level associated with the 
SYS_JNFO, APP_INFO, SYS_TRACE, APP_TRACE, 
and AUDIT parameters may be specified as ON or OFF. The 
default value for any trace level is OFF. The WARNING, 
MAJOR, and CRITICAL parameters may also be specified 
as ON or OFF. It is noted that there exists a hierarchical 



relationship between these three error levels. For example, if 
WARNING is ON, it implies that all the error levels are ON. 
If MAJOR is ON, then CRITICAL is ON. 

The TRACE_LOG_SIZE parameter controls the maxi- 
mum size of a trace/log file. When the trace or log file 
reaches the specified size, it is moved into the files named 
<componentnamexpid> .trc.bk or 
<componentnamexpid>.log.bk, respectively. The default 
value for the trace/log file size is 100K bytes. 

A trace statement is typically used to write a developer 
specified string to the <ComponentNamexpid>.trc file if 
the trace category specified by the developer, which is 
generally hard coded in the program, is ON at run time. A log 
statement is generally used to write a specified error mes- 
sage to <ComponentNamexpid>.log file if the category 
specified by the developer, which is generally hard coded in 
the program, is set to ON at run time. It is noted that the 
developer typically specifies an error number that is used to 
retrieve the error message from an external Message Cata- 
log. 

In order to write a message into the log/trace file, the 
developer may use the macro DX_TL as shown below: 

DX_TL(DX_ARGS, Category, StringToLog/ 
ErrorNumber[,arg 1 [,arg2]]); 
The macro DX_ARGS includes parameters such as 
filename, line number, time and thread ID that are automati- 
cally written into the trace/log messages. Category is speci- 
fied by the following enumerated data types: 

EXAMPLE #35 



enum DX_TL_CATEGORY 



{ 



CRITICAL, 

MAJOR, 

WARNING, 

SYS_INFO 

APP_INFO 

SYS_TRACE, 

APP_TRACE, 

AUDIT 



StringToLog is specified by the developer as a trace 
message and is written into the 
<ComponentNamexpid>.trc file (type char *). For 
Example, an AUDIT message could include the details of a 
Common Object typically stored as a formatted string. 
ErrorNumber is specified by the developer for a log message 
(e.g., when the category is CRITICAL, MAJOR or 
WARNING), and is used to index into a Message Catalog to 
retrieve the error message to be logged. The error message 
numbers are defined as an enumerated type as shown below: 



EXAMPLE #36 



enum DX_ERROR__NUM 



{ 



FT LE_NOT_FOUND, 
INVALIDED ATA 



} 



65 



A component using the Tracing/Logging Utility needs to 
include the following statement: tfinclude "traceLogUtil.h". 
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The definition of DX_TraceLogObject and other related 
definitions are provided as follows: 

EXAMPLE #37 



DX_INDICATOR 
{ 

ON, 
OFF 

class DX_TraceLogObject{ 

friend class DX_SysConagObject; 

public: 

//cannot delete the pointer returned 
//call Dcletclnstancc( ) 
static DX_TraceLogObjed* Instance 
(char *componentName, 

DX_INDICATOR *iniiTrcLogCatInd, 
char* iruflrcLogDir, 
long initTrcLogSizc); 
//cannot delete the pointer returned 
//call Deletelnstance( ) 
static DX_TraceLogObject* Getlnslance( ); 
static void Delete Instance( ); 
//used to write a trace/log message specified by msg 
/Ao the //.trc/.log file 
void Write( 

char * filename, 
int lineno, 
char* context, 
char* threadld, 
DX_TL_CATEGORY ctg, 
char* msg, 
char* argl-O, 
char* arg2=0); 
//used to write a log message specified by errNo 
//(access Message Catalog 
//to get the message) to the.log file 
void Write( char * filename, 
int lineno, 
char* context, 
char* threadld, 
DX_TI^CATEGORY ctg, 
EerrorNumber errNo, 
char* argl^), 
char* arg2=0); 

private: 

static DX„TraceLogObject* instance; 
//default constructor - does nothing 
DX_'DaceLogObject( ); 

//constructor used to initialize the Tracing/logging object 
DX_TraccLogObj'cct(char •componentName, 

DX_INDICATOR *irutTrcLogCatInd, 

char* initTrcLogDir, 

long initTrcLogSize); 
//destructor 

~DX_TraceLogObject( ); 

//called by sysConfigObject when a deconfigset 

//command modifies any parameters 

void ReconfigParameters(char* componeatName, 

DX_I NDICATOR 'newTrcLogCatlnd, 

char* newTrcLogDir, 

long newTrcLogSize); 
/Ao retrieve the message from the catalog 
char* Get Message Fro mCatalog(int errNum, 

char" argl, 
char* arg2); 

/Ao store the settings of the trace/log levels 
DX_lNDICATOR trcLogOategorylnd 
[ DX_NUM CATEGORIES]; 

DX_Boolean ChectLogFileSizefofstream &logStream, 
char * file Name, 
long size); 

void CloseLogFile(ofstream &logStream); 
DX_Boolean OpenLogFile(ofstream &iogStream, 
char 'fileName); 

/Ahe out streams for the trace and log files 
ofctream txcStream; 
ofstream logStream; 
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-continued 



int logStreamlsOpen; 






int trcStreamlsOpen; 






long logSize; 






char traccFileName[MAX_FILE_ 


_NAMEJ 




char logFilcName[MAX_FI LE_N AM E]; 




DX_Mutex - trcLock; 






DX_Mutex* logLcck; 






DX__Mutex* trclogParamsLock; 






}; 

class DX_TraceLogFormatControl 
{ 

public: 










static void Write Fo rata ttedTrace Log 




(ofstream& outStream, 








char 


•category, 




char 


•time, 




char 


•filename, 




int lineno, 




char- 


1 threadld, 


}; 


char 


•message); 



The Write( ) method in the DX_TraceLogObject calls 
WriteFormattedTraceLog( ) of 

DX_TraceLogFormatControl Object to write to the trace/ 
log stream in a specific format. Thus, the implementation of 
the DX_TraceLogFormatControl object may be changed to 
accommodate the needs of users who would want to imple- 
ment a desired formatting style. The contents of Trace/Log 
30 messages that are logged include the following: Category; 
File name; Line Number; Thread ID; Time; and Context. 

The System Configuration Object contains an instance of 
the Trace/Log Object, which is initialized with parameter 

35 values specified in the Configuration file. When the user 
modifies the Trace/Log parameters at run time, typically by 
use of the DX_ConfigSet command, a signal is sent to the 
applicable component which calls the method 
ReconfigParameters( ) on the System Configuration Object 

40 to re-initialize the parameters. This method, in turn calls 
ReconfigParameters( ) on the DX__TraceLogObject. 

An error/event may occur at a very low level in the code 
(e.g., database space exhausted). It is important to report this 
45 low level event, but it is also important to report the context 
of what was trying to be achieved within the application 
when this low level error occurred. The application devel- 
oper is provided with macros to define a context within the 
developer's code. The set of macros provided for this 
purpose include: INIT_CONTEXT; CONTEXTJEGIN; 
and CONTEXT_END. In general, every function using the 
context macros should first use the macro INIT__ 
CONTEXT It is noted that, if INIT_CONTEXT is not 
called before defining CONTEXT_BEGIN, the code may 
not compile. 

The beginning of a context may be defined using the 
macro CONTEXT_BEGIN, and the end of a context can be 
defined using the macro CONTEXT__END, as is indicated 
in the following example. The CONTEXT_BEGIN macro 
takes the argument Context Number. This context number is 
used to access the Context Catalog of an application and to 
retrieve the context string. It is noted that nested contexts are 
generally not allowed. If a CO NTEXT_BEGI N is called 
before the previous context is ended, an implicit 
CONTEXT_END for the previous context is assumed. The 
following example is provided: 
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EXAMPLE #38 



Funcl( ) 



{ 



[NIT_CONTEXT, 

CONTEXT_BEGIN(EcontcxL0); 

// all the trace/log statements in this region wilt 

// have the context information 

// specified by EcontcxtO. 

CONTEXT__END; 

CONTEXT_BEGIN(Econtextl); 

// in Econtextl 

CONTEXT_END; 
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15 



An object DX__ContextObject is used to store the context 
information and is defined as follows: 

EXAMPLE #39 20 



class: DX_ContextObject 
{ 

public 

DX_ContextObjcct( ); 

virtual-DX_ContextObject( ); 

void SetCurrentContext(EcontextNumber cxt); 

char 'GctContextFromCatalDg(EcontextNumber cxt); 

char* GetContextStr( ); 
private: 

char* cunentConlext; 

} 



25 



30 



The method GetContextStr( ) is called by every log/trace 
statement to include the current context information in the 
message. GetContextFromCatalog( ) is used to retrieve the 
Context information from the context catalog. 

Within a given function, INIT_CONTEXT declares a 
pointer to a DX_ContextObject, referred to as dx_context, 
and initializes it to point to a global dummy 
DX_ContextObject, whose context string is blank. It also 
declares and initializes a variable dx_init_context. The 
definition of the INIT_CONTEXT macro is as follows: 

EXAMPLE #40 

#define INIT_CONTEXT DX_ContextObject* 
dx_context=&dummy; \ 
int dx_init__context=l; 

The macro CONTEXT_BEGIN, described in the follow- 
ing example, checks whether dx_init__context is initialized 
or not. The significance of this check is to make sure that the 
function does not compile if INIT_CONTEXT is not called 
before the first occurrence of CONTEXT_BEGIN. It then 
initializes the DX_ContextObject pointer to point to a new 
DX_ContextObject instance storing the context string 
specified by the context number argument. 

EXAMPLE #41 

#define CO NTEXT_BEGIN(cxt) 
if(dx_init_context){\ 
dx_context-new DX_ContextObjecl; \ dx_context 
>SetCurrentContext(cxt); } 
The macro CONTEXT_END deletes the 
DX_Context Object instance created by CONTEXT_ 
BEGIN, as can be seen in the following example. 
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#define CONTEXT_END delete dx_context; \ 
dx_context=&dummy; 

Various aspects of the performance and statistics moni- 
toring features of the data exchange system infrastructure 
will now be described. An automated performance monitor- 
ing mechanism is used to provide load and throughput 
statistics for each system input queue on a regular interval 
basis. The statistical data may be used to generate a perfor- 
mance report. The monitoring interval and output type and 
location is typically externally controlled. 

The following statistics are typically recorded when 
monitoring is performed on the queue: (1) number of the 
messages processed in the system input queue; (2) the 
average message cache time in the system input queue, by 
priority; and (3) the average message processing time from 
the system input queue, by priority. The following statistics 
are typically recorded when monitoring is performed on the 
disk space and database table space usage: (1) the percent- 
age of the disk space usage if the queue storage type is 
FLATFILE; and (2) the percentage of the table space usage 
if the queue storage type is DATABASE. 

The Monitor is implemented as a threaded operation that 
exists for the duration of the executable whenever the 
monitor is triggered ON. At externally controlled intervals, 
this thread is activated, retrieves all pertinent statistical data, 
and then writes to the Statistics Log for each of its system 
input queues. The statistical log is typically an ASCII file. 

When queue monitoring is being performed (i.e., 
QUEUE_MONITOR~ON), the monitor writes the log file 
into a $DX_HOME/DX_MonitorLog directory. The moni- 
tor writes the number of message processed in the system 
input queue, the average processed message cache time in 
the system input queue, and the average message transaction 
time from the system input queue by priority into an ASCII 
file on a regular time interval. Each system input queue of 
a monitor instance has its own ASCII log file. The name of 
the file follows the system file name schema (e.g., 
AppName >_<QueueName> . Mon_Log). 

This file stores the most current queue performance 
information. The maximum file size is defined in the system 
configuration file. After the file reaches its maximum size, 
the monitor moves it to a backup copy named 
<AppName>_<QueueName>.Mon_Log.bk and creates 
and writes the performance information into the new 
<AppName>_<QueueName>.Mon_Log file. The system 
typically retains only one backup copy of the monitor log 
files. 

The monitor writes the log file in the same format 
irrespective of whether the queue is file based or database 
based. The format of the report file is provide in Table 1 
below: 

TABLE 1 

Avg Avg 

Number Avg Avg Number Co- Pro- 
Prior- Of Cache Process Prior- Of che cess 
Tune ity Msg Tune Tune ity Msg Time Tune 



where, Time represents the time stamp of the record; Priority 
represents the priority of the queue; Number of Messages 
represents the number of message processed in the last time 
interval; Average Cache Time represents the average lime 
65 mat a message stays in the queue (i.e., the time between 
dequeue and enqueue); and Average Process Time represents 
the average transactions time for a message (i.e., the time 
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between commit successful and dequeue). The report head- 
ers repeat for each priority queue supported in the system. It 
is noted that the data fields are delimited by a comma so that 
the log file may be easily imported into spreadsheet soft- 
ware. 

When disk space and/or database table space usage is 
being monitored (i.e., SYSTEM_INFO_MONITOR=ON), 
the monitor writes the usage of the disk where the queue files 
located into an ASCII file on a regular time interval if the 
queue is rile based. The name of the file follows the system 
file name schema (e.g., <AppName>_SysInfo.Mon_Log). 
The maximum file size is defined in the system configuration 
file. After the file reaches its maximum size, the monitor 
moves it to a backup copy named <AppName>__ 
SysInfo.Mon__Log.bk and creates and writes the perfor- 
mance into the new <AppName>_SysInfo.Mon_Log file. 
The system retains only one backup copy of the monitor log 
files. The format of the report file is give below in Table 2: 
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The Monitor Object is instantiated by the 
DX„SysConfigObject instance or by calling the static 
method DX_Moniton:Instance( ) directly. There is only one 
DX_Monitor thread running per executable component. 
The monitor thread is spawned whenever the MONITOR in 
the system configuration file is triggered to ON, The monitor 
thread exists until the MONITOR is triggered to OFF. The 
implementation of the monitor impacts three areas. The 
Queue Manager provides the queue performance data. The 
DX_SysConfigObject provides the configuration change 
handling and the monitor object instantiation. The 
DX_Monitor Object spawns or kills the monitor and gen- 
erates the monitor log files or log table in the database. The 
methods added in the DX__Queue classes are listed below: 



10 
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TABLE 2 



Tune 



DiskUsage 



where, Time represents the time stamp of the record in the 
log file; and DiskUsage represents the percentage of the file 25 
disk usage if STORAGE_TYPE=FLATFILE. Again, the 
data fields are delimited by a comma. It is noted that the 
database table space usage is generally not available to the 
application user, such that only the system administrator has 
the privilege to view it. As such, the monitor does not 30 
perform monitoring for the database table space usage. 

Changes in the run-time monitor configuration are 
handled through the system configuration utility. The Sys- 
tem Configuration Object contains an instance of Monitor 
Object which is initialized with the monitor configuration 35 
parameter values specified in the System Configuration file 
and saves them as configuration member data. When the 
user modifies the Monitor Configuration parameters at run 
time, typically be use of the deconfigset command, a signal 
is sent to the component which calls the method 40 
ReconfigParameters( ) on the System Configuration Object 
to re-initialize the parameters. This method, in turn, calls 
reconfigparameters( ) on the Monitor Object and updates the 
configuration member data. The monitor thread reads the 
configuration member data when it becomes active in the 45 
next time interval. As such, the monitor configuration 
parameters are modifiable at run-time. 

In the system configuration file, the monitor uses the 
following parameters. To turn the monitor output ON or 
OFF, the MONITOR-ON/OFF parameter is used. The 50 
default is OFF. To turn the monitor output ON or OFF for the 
queue performance, the QUEUE_MONITOR -ON/OFF 
parameter is used. The default is OFF. To turn the monitor 
output ON or OFF for the system information, the 
SYSTEM_INFO_MONITOR-ON/OFF parameter is used. 55 
The default is OFF. To set the monitor poll interval in terms 
of seconds, the MONITOR_INTERVAL-XX (i.e., number 
of seconds) is used. The default interval is 600 seconds. The 
maximum and minimum poll intervals are predefined. The 
maximum size of the log file is set using the parameter 60 
MONITOR_LOG_FILE_SIZE-XXX (i.e., number of 
blocks). The default size is 1000 blocks. The name list of the 
system input queues is established using the SYSTEM_ 
INPUT_QUEUE_NAMES-* *, *** parameter 

format, where the names are separated by commas. The 65 
default is empty. Also, the monitor gets the "DX_HOME" 
parameter from the system environment. 



DX_QueueObjcct: 

Class DX^_QueueObjecl { 
Private: 

long cnQTtmcStamp; 
long deQTimeStamp; 



Public: 

long GetObjectEnQTime( ); 
Void SetObjeaEnOTmefint time); 
long GetObjectDeQTime( ); 
Void SetObjectDcQTime(int time); 



EXAMPLE #44 



DX__Queue: 
Class DX„Qucuc { 
Public: 



virtual void GetQueuePerforma nee (long *pNumOfMsgProcessed ) 
long *pAvgMsg- 
CacheTtme, 
long 'pAvgMsg- 
ProcessTime) - 0; 

virtual void Reset( ) » 0; 



}; 

Q ass DX_FUeQueue : public DX_Queue { 
Public: 



void GetQueuePerfonnanceQong *pNumO£MsgProcessed, 
long *pAvgMsg- 
CacheTiine, 
long "pAvgMsg- 
ProcessTime); 

void Reset( ); 



Class DX_FileSubQueue { 
Public: 



long GelNumOfMsgProcessed( ); 
long GelTotalMsgCacheTime( ); 
long GctTotalMsgProcessTime( >, 
void Reset( ); 
Private: 



long totalMsgCacheTime; 

long total Ms gProccssTimc; 

long numOfMsgCommited; 

void SetDequeueTime(DX_QueueObject *qo); 
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-continued 



-continued 



void SetEnQueueTime(DX_QueueObject *qo); 

void CompleteCtommitCalculatioii(DX_OueueObject *qo); 

Class DX_DBQucue : DX_Queue { 
Public: 



Private: 



void GetQueuePerformance(long "pNumOfMsgProcessed, 
long *pAvgMsg- 
CacheTime, 
long *pAvgMsg- 
ProcessTime ); 

void Reset( ); 
private: 



10 



} 



// Pointer to DX_Monitor instance 
DX_Monitor *pMonitor; 

// Method to instantiate DX_Monitor after DX_Sys- 

ConftgObject constructor 

void InitMonitor(const char *appName); 

// Get Monitor config parameters 

void GetMonitorParam(stnxct MoaConfig- 

Type * monConfig); 



long "numOfMsgCbrnmited; 

long "totalMsgCacheUme; 

long *totalMsgProcessTune; 

void SetDequeueTime(DX_OueueObject # qo); 

void SetEnqueueTime(DX_QueueObject *qo); 

void SetOrigEnqueueTtme(DX_QucueObject *qo, 

const char* timeStr); 

static void CommitCalculations(DX_Queue 
Transaaion & transaction); 
time_t ConvertStringDatefcoast char* timeStr); 



It is noted that InitMonitor( ) instantiates the DX_Monitor 
15 instance, and ReconfigPararaeters( ) read the monitor con- 
figuration parameters or set the default configurations. 

EXAMPLE #47 



20 



DX_Moniton 
class DX_Monitor 



25 



The data collecting mechanism is as follows: set the 
enqueue time stamp of the queue object when the message 
is enqueued; set the dequeue timestamp of the queue object 
when the message is dequeued; calculate the message cache 
time and the process time when the message is dequeue- 
committed from the queue successfully; and reset the 
totalMsgCacbeTime, totalMsgProcessTime, numberOfMsg- 
Processed to zero upon request. 

An additional method added in the DX-Queue classes is 
provided as follows: 

EXAMPLE #45 
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DX_QueueMangen 

Class DX_QueueMangcr { 
Public: 

EretumCodes GetQueuePerformance(char » inputQName, 

long •pNumOf- 
MsgProcessed, 
long *pAvg- 
MsgCacheTime, 
long *pAvg- 
MsgProcess- 
Time, 
bool reset- 
Flag = true); 

void ResetAlI(const char *qNameList); 



The methods added in DX__SysConfigObject are 
described below: 



EXAMPLE #46 



DX_SysConfigObjeci: 

Class DX_SysConfigObject { 
Public: 



60 
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static Boolean MonitorQueueIsOn( ); 



{ 
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}; 



friend class DX^SysConfigObject; 
public: 

static DX_Monitor* Instance(const MonConfigType &monConfig, 

const char *appName); 
DX_Monitor *Geanstance( ); 
protected: 

void ReconfigParameters(consl MonConfigType &monConfig); 
Boolean MonitorQueueIsOn( ); 
// Can only be deleted by DX_SysConfigObjcct 
virtuaP~DX_Monitor( ); 
private: 

DX_Monitor(const MonConfigType &mon- 

Conflg, const char *appName); 

static void* RunMonitorfvoid *Arg); 

void StartMonitorThread( ); 

// set the monitor config parameters 

void SetConflgParams (const MonConfigTVpe AmonConfig); 

II write the queue performance into a log file 

void WriteToQueueLogFilc(const char * inputQName, 

long 'pNumOfMsgProcessed, 
long •pAvgMsgCacheTime, 
long •pAvgMsgProcessTune, 
const MonConfig- 
Type & cur Config, 
int numOfPriority); 

void GetNewLogTiUeLine(char *titleLine ) int numOfPriority); 

void GetLogEntryLine(char "logEntryline, 

long "pNumOfMsg, long *pMsgCacheT, 

long "pMsgProccssT, 
int numOfPriority); 

void GetQueueInfo(const MonConfigType &curConfig); 

void GetSystemlnfo (const MonConfigType &curConfig); 

void WriteTbSysLogFile(float diskUsage, 

const MonConfigType fccurConfig); 

// Data members 
static DX_Monitor* _instaace; 
// lock for monitor config parameters 
DX_Mutex* MonConfigMutex; 
// monitor config parameters 
MonConfigType config; 
char appName[MAX_NAME_LEN]; 
DX_QueueManager *pQMgr, 



Various utilities may be used to facilitate data exchange 
system administration and maintenance activities. These 
utilities include component shutdown, queue monitoring, 
queue viewing, and queue modification utilities. Descrip- 
tions and implementation examples of each of these utilities 
are provide below. 

A shell/bat script DX_Shutdown is provided to shutdown 
individual components identified by the component name. 
DX_Sbutdown needs to halt all the threads of execution 
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gracefully before shutting down the component. The syntax 
of the DX_Shutdown script is DX_Shutdown 
<ComponentNamexPid>. An implementation example is 
provided as follows. DX„Shutdown script uses 
DX_ConfigSet to communicate with the component being 
shutdown. DX_ConfigSet can be used to raise a signal or 
event after adding a parameter to the config file to indicate 
that an instance of the particular component is to shut down 
gracefully. The configuration parameter used is 
DX_SHUTDOWN and its value is set to the PID of the 
instance to be shutdown. 

As in the case of run-time configuration management, the 
ReconfigParameters( ) function on DX_SysConfigObject 
will be called. In this function, the DX_SysConfigObject 
first checks if the signal/event received corresponds to 
Shutdown and if the PID specified is its own PID. If so, it, 
in turn, must make sure that no new transactions are started, 
and waits for all of the current transactions to be completed. 
This involves calling the macro DX_SYSEXIT. It is noted 
that, before shutting down, the entry in the configuration file 
should be deleted by the exiting process. It is possible that 
the component aborts prior to cleaning up the configuration 
file. This stray entry does not effect the start up of any other 
component using the same configuration file. 
DX_ConfigSet is also responsible for clean up of stray 
DX_SHUTDOWN entries in the configuration file. 

The queue monitoring administration and maintenance 
utility will now be described. The sequence of enqueue/ 
dequeue operations performed on a Queue may be logged 
into a special audit file named <Queuename>.qlog (stored in 
directory $(DX_HOME)/DX_Qlog) specified by environ- 
ment variable DX_QLOG. The audit logging can be 
switched ON or OFF at run time using DX_QMonitor 
utility. The syntax for this utility is DX_QMonitor 
<QueueNamexON/OFF>. An example of the queue moni- 
toring utility is given as follows. 
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The DX_Qlog directory stores a registration file for every 
Queue in the system (<Queuename>.reg). This file stores the 
information whether audit logging for a particular queue is 
ON or OFF (i.e., 1 or 0). It also stores the list of Components 
5 and their PIDs that are currently using the Queue. This 
information is used by the DX_Qmonitor to determine 
which components are to be informed when the audit 
logging status of the queue is changed. 

10 Every instance of a component instantiates a 
DX_QueueLogMgr object. When the instance wants to 
access a particular queue for the first time, which may be a 
new 5 or an existing queue, the DX_QueueLogMgr looks 
up the registration file for the queue in DX_Qlog directory 

15 to determine the audit logging status and also writes its name 
and PID into the registration file. It is noted that 
DX__QueueLogMgr creates a registration file for a queue in 
case it does not exist. The default value for Qmonitor status 
is OFF(i.e., 0). 

20 

The DX_QMonitor utility informs the change in the audit 
logging status of a queue to all the processes using the 
Queue by updating the registration file and raising an 
event/signal to inform all the components to update their 

25 DX_QueueLogMgr objects. This command is also respon- 
sible for cleaning up entries in the registration file corre- 
sponding to components that died without cleaning up the 
registration file. Whenever an Enqueue or Dequeue opera- 
tion is committed, a check is made on the 

30 DX_QueueLogMgr to see if audit logging is ON or OFF 
and information is logged in case it is ON. When an instance 
is terminating, the destructor of DX_QueueLogMgr should 
update all the registration files in which it has created an 
entry. An implementation example is provided as follows: 

35 

EXAMPLE #48 



class: DX_OueucLogMgr 
{ 

public: 

// create an instance of the object by calling the constructor 
// delete using Delete Instance( ) 

static DX_QueueLogMgr* Instance (char* ComponentName=0); 

// delete the object 

static void Delete Instance ( ); 

// Checks if the QueueStatusList has an entry 

// for the particular queue and if so checks 

// if the entry indicates whether the 

// queue monitoring is on or off and logs the 

// QueueObject accordingly 

static void DumpQLog(EQueueOperation op, 

char* queueName, 

DX__QueueObject* q 0 ); 
// if you want to monitor a queue, an entry in 
// the queue status list should be created first 
// by giving the queue name and the pid. The function 
// reads the .reg file and initializes the entry 
// accordingly. 

EreturnCodes InsertQueueStatusList(char* QName, int pid); 
// if queue monitor changed the queue registration file, reset the 
// object, read the reg file and update the queueStatuslist; 
EreturnCodes ReconfigQueueSutusList( ); 
private: 

DX_Mutcx* listLock; 

static DX_QueueLogMgr* instance; 

char ComponentName[ MAX_NAME_LEN]; 

char QlogDir[ M AX_FILE_N AMEJ 

DX_OueueLogMgr(char* icComponeniName=0^:har* qlogdir=0); 
virtual~DX_QueueLogMgr( ); 
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Exeturn Codes DeleleFromRegFiles(char* ComponentName,int pid); 
DX_IN r DICATOR GetStatusFromRegFile(char* regFileName, int& regFile Exists); 
char* GetQRegFUeName(char* QNamc); 
EretumCodes FindQueueLogStatusInfo(char* inQName, 

DX_QueueLogStatusInfo" copy); 

RWDlistCollectables •queueStatusList; 

class DX__GueueLogStatusInfo: public RWCollectable 
{ 

friend class DX_QucueLogMgr; 
private: 

char qName[MAX_NAME_LEN]; 

DX__INDICATOR qLogSlatus; 

char qLogFileName[MAX_FtLE__NAME]; 

RWDECLARE_COLLECTABLE(DX_QucucLogStatusInfo); 

DX__C5ueueLogStatusIn&>( ){ }; 

// During construction if inQLogStatus is ON 

// open the logStream for QName.qlog in directory DX_HOME/DX_QLOG 
DX_QueueLogStatusInfo(char* inQName, 

DX_INDICATOR inQLogStatus, 

char* qlogdir); 
// close all the streams which are open 
~DX_QueueLogStatusInfo( ); 
char* GetQName( ); 
DX_JNDICATOR GctQLogStatus( ); 
char* GetQLogFileName( ); 

// if set to on, open stream, if set to off close the stream 
EretumCodes SetQLx)gStatus(DX_[NDICATOR inStat); 

idefinc DX_QLOG(QucueOp,QueueName,qo) DX_QueueLogMgr::\ 

DumpQLog(QueueOp,QueueName,qo) \ 



The queue viewing administration and maintenance util- 
ity will now be described. DX_Qview <queue_name> 
[priority] permits viewing of all items in a Queue identified 
by its name. This information may be obtained using the 
GetQueueView( ) method on DX_QueueManager object. 
DX_GetCO <oidval> permits viewing of the common 
object for a particular OID in the queue. This utility uses the 
Demarshal( ) method provided in DX_CommonObject 
class. Other viewing options include the following: viewing 
the queue entry corresponding to common object specified 
by its name or OID; viewing all queue entries enqueued by 
a particular source; viewing all queue entries having a 
particular status; and viewing the names of all objects in the 
queue. 

Modifying the contents of Queues involves the 
DX_QMove utility which provides for the following: 
Dequeuing of an entry from the queue identified by the OID 
of the common object; and Enqueuing the entry to another 
queue. The syntax for this utility is DX__QMove Source„ 
Queue Destination_Queue OID. 

Concerning data exchange system security, the basic 
security control is focused on the queue files access or the 
database tables access. The file access control requires the 
application user to be in a specific user group. The user 
group should be set before the application runs. The data- 
base table access control requires the application users to 
have the correct user name and user password. The user 
name and user password may be set in the environment 
variables or be hard coded in the application programs. In 
one embodiment, all applications share one database user 
account. This user account has privileges to create/update/ 
delete tables in the view. 

As was previously discussed in connection with FIG. 9, 
the Processing Thread Pool is a pool of native system 
threads whose maximum number is externally controlled. 
The function of the Processing Thread Pool is to provide a 
run-time configurable thread of control for the data 



exchange system application. The thread controller will also 
provide a request FIFO (First-In-First-Out buffer) that will 
buffer threaded operations when all threads are in use, and 
process these requests as system resources are made avail- 

35 able. The thread controller's resources are configurable at 
run-time through the system administration. 

The thread controller is implemented as 
DX_ThreadController, which is automatically initialized by 
the DX_SysConfigObject. It may alternatively be used in a 

40 standalone mode as well. The DX_ThreadController opera- 
tions will wrap the platform specific thread package 
operations, making them invisible to the user. Use of the 
DX_ThreadController does not preclude a developer from 
using native thread package calls. 

45 The DX_ThreadController is implemented as a singleton 
object which makes system tuning and performance man- 
agement an easier task. The DX_ThreadController is 
instantiated by the DX_SysConfigObject at startup. All 
parameters used by the DX_ThreadController are config- 

50 urable at runtime via the DX_ConfigSet tool, with any 
changes being applied to the next thread created following 
the configuration change. 

A macro called DX_Thread_Execute( ) is provided for 
ease of use. This macro retrieves the DX__ThreadController 

55 instance from the DX_SysConfigObject and then invokes 
the DX_ThreadController::Execute( ) method. The method 
DX_ThreadController::Execute( ) behaves exactly the same 
as if a call was invoked to create a new thread. A pointer 
must be passed to the function and as well as a pointer to the 

60 arguments. Internally, the DX_ThreadController uses the 
class DX_ThreadRequest when a thread is not available to 
provide a FIFO buffer that will store the function pointer and 
argument pointer. Each time a thread completes execution, 
the FIFO is checked for the presence of entries. If there are 

65 entries in the FIFO, the first entry in the buffer is removed 
and executed. An example of DX_ThreadController imple- 
mentation is provided in the following example: 
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EXAMPLE #49 



class: DX_ThreadComroller 

{ 

friend class DX_SysConfigObjcct; 
public: 

static DX_ThreadCont roller* Instance ( ); 
virtual~DX_ThreadController( ); 

EretumCodes Executefvoid* (* functionPtr)(void*), void* args); 

class DX_Thread Request : public RWColIectable 
{ 

friend class DX_ThreadControIler; 
private: 

DX_ThreadRequest(void -(*functionPtr)(void *), void *args); 
virtual ~DX_ThreadRequest( ); 
// data members 
void* function; 
void* args; 

}; 
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A DX_Utils library provides the DX_Mutex class for 
platform independent mutex protection, an example of 
which is provided below. The DX_Mutex class does not 
require use of the DX_ThreadController class. 

EXAMPLE #50 



class: DX_Mutex 
{ 

public: 

DX_Mutex(const char* name); 
virtual ~DX_Mutex( ); 
int lock( ); 
int unlock( ); 
private: 

char* Name; 

}; 
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For purposes of data internationalization, Unicode UTF-8 
formatting is provided to store all attribute value strings 
using wide character strings. Code conversion functions to 
convert a Unicode string to UTF-8 string and vice-versa are 
also provided. These conversion methods are used to store 
any user-specified data internally in UTF-8 format. To 
support language localization, all message strings use an 
external message catalog. The interface provided by the 
DX_CodeConversion class is as follows: 



52 

-continued 



EXAMPLE #51 



class: DX_CodeConversion 



{ 



typedef struct { 



long 



cmask; 
cval; 
shift; 
Imask; 
Ival; 



}Tab; 



public: 

// memory for out is allocated by the func 
// and needs to be deallocated by the caller 
// the return value is the length of the unichar 
// 5tring(number of unichars) or -1 if the 
// conversion failed 

static int Co n ve rt UTF8T0 UCS (co nst char *in, 



UNICHAR* &out); 
// memory for out is allocated by the func 
// and needs to be deallocated by the caller 
// the return value is the length of the utfS string 
// and -1 if the conversion failed 
static int ConvertUCSnbUTF8(const UNICHAR *in, 

char* &out); 

private: 

static Tab tab[ J 

static int MHToWCfUNlCHAR *p, const char *s, size_t n); 

static int WCToMB(char *s, UNICHAR wc); 

// In the code-conversion functions it is assumed 

// that the memory 

)l for the in , out strings are 

// out_len are allocated before the function is called. 
// out should be size of(UNlCHAR)*(strlen(in>l)) bytes long 

static int PwConvertUTF8ToUCS(const char * in, 

const int in_len, 
UNICHAR "out, 
int *out_len); 

// out should be (UCSStrlen(in)M +1 ) bytes long 

static int PvtConvertUCSToUTF8 (const UNICHAR "in, 

const int iruJcn 
char "out, 
int *out_len); 



}; 
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A skeleton main( ) function is provided to illustrate the 
system initialization and startup procedures required for 
each component of the data exchange system application. 
30 This includes operations such as database connection, sys- 
tem resource configuration, thread control, etc. In addition, 
a System Health Monitor thread is provided which, on a 
timed interval, polls all system resources to ensure that 
system operation can continue. This thread invokes the 
system checking operations System Configuration Object. 
The sample code provided below illustrates the ease of 
initializing system components and application operations. 
This sample is part of the DX_Engine executable, which 
serves as the core of the data exchange system. 



40 



45 



EXAMPLE #52 
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60 



#define COMPONENT_NAME "DX_Engine" 
void* Process InputQueues (void* args); 
int main (int argc, char* argv[ ]) 
{ 

// Initialize the SysConfig object and all system resources 
DX_S YS INiT(CO MPO NE NT_N AM E) ; 
void **params; 

params - (void**)malloc(2 * sizeof(long)); 
int DQthrcads - atoi(DX_SysConfigObjcct::Instancc( )- 
>FindValueC*DEQUEUE_THREADS")); 

// Start threads for dequeuing input requests 
for (int i=0; i<DQthreads; i++) 

DX_Ou cue Manager • QueucMgr » DX_Oueue- 
Manager::GetInstance( ); 

DX„QueucTrans action* Trans ° new DX_Queuc- 
Transaction(QueueMgr); 
paramsfO] - Queue Mgr; 
params[l] - Trans; 

DX^JIlwad_Execute(ProcessInputQueues ) params); 

} 

free(params); 

while(l) 

{ 

// loop so app doesn't exit 
// sleep or do something else 

} 

DX_SYSExrr, 
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-continued 



-continued 



return 0; 



A set of libraries that cooperate in tandem provide for 
basic request routing. The DX_Rules library is a dynamic 
shared library that serves to provide a stub API for appli- 
cation developers. The DX_Eogine executable makes use 
of both the DX_Rules and DX_Route libraries. When 
custom rules and routing logic for an application have been 
designed and implemented, the DX_Rules library should be 
replaced with the new custom library using the API defined 
in "DX_RulesAPI.h'\ The DX_Rules( ) method is auto- 
matically invoked from within DX_Route( ). The 
DX_Rules API is defined as EreturnCodes DX_Rules 
(void* args). 

The DX_Route library serves two primary purposes. Its 
first job is to invoke any customized rule and routing 
implementation by calling the DX_Rules( ) function in the 
following manner: 



EXAMPLE #53 



EreturnCodes DX_Route (void* args) 

^ DX_TL(DX_ARGS ) SYS_[NFO, "Entering 
DX__Route(void* args)"); 
void "*params; 
params «• (void**)args; 

DX^CommonObjea* PcommonObj = (DX_Common- 
Object*)params[0]; 

DX_OueueManager* Qmgr - (DX_Queue- 
Manager*)params[ 1 J 

DX_QueueTransaction* T = (DX_Queue- 

Transaction*)params[2l; 

if (PcommoaObj) 

^ if(DX_Rulcs(args) — NOT_POUND) 
{ 

// No rules implemented, so do default routing 
if (DX_Defauk_Route(args) — SUCCESS) 
return SUCCESS; 

else 

return FAILED; 



} 



} 



DX_TL(DX_ARGS,SYS_[NFO, "Returning 
from DX_Route(void* args)"); 
return SUCCESS; 



} 



if (Qmgr->Dequeue(-DX_SYSTEM_IN", PnewCO, T) ■ 
SUCCESS) 
5 { 

if (PnewCO) 
{ 

void **params; 

params - (void**)malloc(3 * sizeof(long)); 
params[0] - PnewCO; 
10 paramsfl] - Qmgr, 

params[2] = T; 

if(DX_Route(params) =» SUCCESS) 
T->Commit( ); 

else 

T->Rollback( ); 
j 5 firee(params); 

else 

T-RollbackC ); 



The DX_Route library also provides a mechanism for 
default request routing, where requests that do not require 
any special business rule processing may automatically be 
routed to one or more output queues. The DX_Default_ 
Route( ) function is automatically invoked when 
DX_Rules( ) returns "NOT_FOUNTT, which is what the 
stub API returns. The DX_Route( ) function is invoked in 
the following manner: 



EXAMPLE #54 



DX_Qucuc Manager* Qmgr - DX_QueueManager::GetInstance( ); 
DX__Qu eucTra nsact io n * T » new DX_OueueTransaction(Omgr); 
T->Begin( ); 



} 
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The default routing information is contained in an ASCII 
file that is specified in each application's configuration file 
using the parameter "ROUTE_TABLE-path/filename". 
The file containing the default routing information pointed 
to by the "ROUTE_TABLE" variable will contain the 
request name and one or more output queues. A maximum 
of 1024 different messages may be defined with a maximum 
of 255 different outputs per request. The following exem- 
plifies a sample default routing table: 

EXAMPLE #55 



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 

% This file contains the default routing 

% information to Dequeue an incoming object, 

% identify it and then send it to an output 

% queue. 

% 

% The entries should be stored in the following manner: 
% 

% ObjectName>output queue,... 
% 

% The default routing limits are: 
% 1024 ObjectNames 
% 255 output queues per entry 



45 



CustomerOrder>OrderSystem, MarketingRecord, Service 

CancelServicoCustomerRecords 

ProblemReport>Service 

50 A further description of a data exchange system queuing 
methodology in accordance with one embodiment of the 
present invention will now be described. In order to provide 
a clean "buffered API," a queued request approach is used. 
Use of interface queues allows the caller of the API to send 

55 its request irrespective of whether the engine core and 
another outgoing adapter are running. The queue interface 
approach of the instant embodiment also provides a mecha- 
nism for buffering the load that may be placed upon a server 
from multiple clients. It also provides the ability to scale the 

60 number of database servers that can process any given queue 
in parallel. 

As was discussed previously, two types of priority based 
queues are used, namely, the incoming Receive Queues and 
the outgoing Send Queues. Each outgoing adapter will have 
65 its own outgoing queue so that any interface specific trans- 
lation or routing may be performed outside the engine core. 
Each instance of the DX_Engine executable has one or 
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more input queues, although only one is allowed for file- 
based queues, and one or more output queues. An instance 
of the DX_QueueManager class is used as a central proxy 
to all queue access, and will be mutex protected and record- 
lock protected, for file-based implementation, or row lock 
protected, for database implementations, to prevent data 
contention. 

Two types of queues are provided, file and database 
queues, both of which are fairly simple implementations that 
allow for a clean breakup to the API. Priority based queuing 
is provided so that requests of high importance can be 
serviced quickly. Multiple queues are used to provide this 
level of functionality, but the implementation is logically 
transparent to users. A user perceives that there is only one 
logic queue with objects of different priority in it. 

The file storage or database tables for the queue are 
created at running time and deleted by queue administration 
process. There are four types of pre-defined priority: NON- 
URGENT, NORMAL; URGENT; and INTERACTIVE in 
order of increasing priority. INTERACTIVE is the highest 
priority, which can block any request having other priorities. 
The priority algorithm ensures that the Dequeue operation 
always returns successfully when the queue is not empty, 
prevents starvation of lower priority entries, and ensures 
more frequent visits on higher priority queues. The priority 
algorithm is implemented on a weighted basis of each 
priority. 

Support for parallel gateways is only available to a 
database queue implementation. File-based queue imple- 
mentations will not guarantee single delivery, i.e., one object 
might be dequeued by multiple process at the same time. All 
parallel access should be completely transparent to any 
participating gateway. The only areas of common resources 
between any parallel gateways are the Enqueue and 
Dequeue operations. The design of the Enqueue/Dequeue 
module ensures that parallel access is made possible without 
any deadlocks or duplicated queue entries by using the 
database supplied row-level locking. 

Since the external API is limited to the Enqueue/Dequeue 
API, the only limit to multiple access is the row-level table 
locking that the database supports. The file based queue 
mechanism uses simple file record -lock to protect from 
multiple updates to the file from multiple threads. The queue 
access operations for file-based implementation are thread- 
safe, such that all the operations are mutex protected. 

The Queue Manager public interface makes use of the 
DX__QueueTransaction object for transaction control. The 
Enqueue( ), Dequeue(), Commit( ), and Rollback ) methods 
take pass-in argument of an instance of the 
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15 



DX_QueueTransaction class which belongs to a running 
thread. The transaction object contains an ordered list of 
operations performed in this transaction. For file-based 
implementations, all operations are maintained in buffered 
memory and are not written into file storage until commit 
time. For database implementations, the database provided 
rollback mechanism is employed, with each transaction 
using its own unique run-time database context. 

The class structure diagram is shown in FIG. 18. The 
public interface, shown in shaded boxes, is used by adapter 
developers, but the non-public interface, shown without 
shading, is intended for internal use only. This usage restric- 
tion is forcefully implemented. 

The following system constants, which are defined in 
DX_Defs.h, are used by the queuing system. 

EXAMPLE #56 
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caum EstorageTypes 



{ 



h 



FLATFILE - 0, 
DATABASE 



cnum EQucucOpcration 



{ 



ENQUEUE - 
DEQUEUE 



static const int NUM_PRIORITIES - 
enum EPriorityCode 
{ 

NONURGENT - 0, 
NORMAL, 
URGENT, 
INTERACTIVE 



The DX_QueueManager class is a singleton class and 
acts as the global access point of all queue operations. It 
contains a list of queues, instances of DX_Queue class, as 

40 its data member. Users, however, do not need to create a 
queue with Queue Manager before using it. The creation of 
the queue is embedded in Enqueue and Dequeue operations. 
Besides the Enqueue ( ) and Dequeue ( ) operations, 
DX__QueueManager also defines interfaces for extended 

45 transaction support, performance monitoring, and queue 
administration. An illustrative example of 
DX__QueueManager implementation is provided as follows: 

EXAMPLE #57 



class: DX_Qucuc Manager 
{ 

friend class DX_QueueTransaction; 
friend class DX_DBQueue; 
friend class DX_Monitor; 
public: 

static DX_QueueManager* Instance(const char* ProcessName, EstorageTypes 

type); 

static void Delete I nstance( ); 

static DX_Queue Manager* Getlnstance( ); 

r , ......... / 

//Queue operation interface 

/- • * / 

//The label and comment arguments will be used for Queue Administration 
Purpose. 

//So queue administration GUI will olso see the name and comment of each CO in 
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the 

//queue. They can be type of UTF-8 encoded string, 7-bit ASCII string or wide 
string. 

//User should not delete pointer to DX_CommonObject after call Enqueue ^ 

EreturnCodes Enqueue(const char* qNamc, DX_CommonObject &co, 
DX_QueueTraosaction Stransaction, const char" oLabel, 
const char* comment, EPriorityCode priority = 
NORMAL); 

EreturnCodes Enqueuc(const char* qNamc, DX_CommonObject &co, 
DX_QueueTransaction &transaction, const UNI CHAR * 
o Label, 

const UNICHAR* comment, EPriorityCode priority - 
NORMAL); 

,.„..„.„.....«.„«....«.....««.««..««-.»»-» -»"/ 
//Caller should free non-NULL pointer to DX_CommonObject 
//Return SUCCESS if Dequeue returned a common object 
//Return FAILED if Dequeue returned a NULL common object pointer 

EreturnCodes Dequeue(const char* qNamc, DX_CommonObject* &CO 

DX_QueueTransaclion &transaction); 
EreturnCodes Dequeue(const char* qName, const char* objID, const char* 
objLabel, 

DX_CommonObject* &co, DX_QueueTransaction 
& transaction); 

/"*" •♦«...*•♦..»..... ♦ 

//The caller of GetCursor is responsible for deleting 
//returned DX_IndexObject* pointer. 

********* ********************************* ******************/ 

DX_IndexObjcct* GetCursor(const char* qNamc, EPriorityCode priority - 
INTERACTIVE); 
/•**« 

//Will set the cursor to the EPriorityCode passed in 



*/ 



******************************************** **** mm *^***/ 



j*********** 



*********************** *********f 



EreturnCodes RcsetCursor(DX_IndexObject &cursor, 
EPriorityCode priority = INTERACTIVE); 



********************************/ 



//There always is a non-null DX__QueueList returned 
//Caller should delete DX_QueueObjectList returned 

//NOTE: DX_OueueUst may be empty if no entries were found 
// 

//USAGE: 

//GetQueueView(DX_QueueObjectList* &list DX_JndexObject &QViewCursor, 
// int size « 0) 

//will return Gentries =< size for EPriorityCode of QViewCursor and ALL lower 
priorities 

//GetOueueView(DX_OueueObjectList* &list, EPriorityCode priority, 
// DX_IndcxObject &QVicwCursor, int size = 0) 

//will return #entries «•< size for EPriorityCode of priority, QViewCursor is 
updated to 

//reflect position of last retrieved entry. 



EreturnCodes GctQueueView(DX_OueueObjectList* &list, 

DX_IndexObject &QViewCursor, int size = 0; 
EreturnCodes GetOueucVicw(DX_QueucObjcctIist* &list, EPriorityCode priority, 

DX_IndexObject AQViewCursor, int size « 0); 
j**** ****************************************** ******************/ 

//Caller should free char** returned twice ***,*j 

char** GetMaDagcdQueucNames(int& number); 
char** GetAllQueueNames(int& number); 
private: 

static DX_QueueManagei* instance; 
char* owner, 

EstarageTypes Implementation; 
char* FileDBDirectory, 
RWGDlist(DX_Queue) OueueList; 
DX_Mutex* mutex; 

DX_QueueManager(const char* processID, EstorageTypes type, const char* 
FileDBDir>, 

~DX_QueueManager( ); 

//Extended transaction support interface 

EreturnCodes Commil(DX__QueueTransaction & transaction); 

EreturnCodes Rol!back(T)X_QueueTransaction &traasaction); 

//Queue administration interface 

EreturnCodes DeleteQueue(const char* qName); 

EreturnCodes FlushQueue(const char* qName); 
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EreturaCodes RushQueue(oonst char" qName, EPriorityCode priority); 
EreturaCodes RemoveFromQueue(DX_QueueObject *object); 
//Performance monitor interface 

//the memory of pNumOfMsgProcessed, pAvgMsgCacheTime, 
pAvgMsgProcessTime 

//should be allocated before invoking this method. 
EreturaCodes GetQueuePer£ormance(char * inputQName, long 
• pNumOfMs gProcessed, 

double *pAvgMsgCacheTune > 
double *pAvgMsgProcess r Iime J 
DX_Boolean resetFlag = TRUE); 
void ResetAH(const char *qNameList); 
EreturaCodes GetDBTableSpaceUsage (float &usage); 
//Internal use 

DX__Queue* FindQueue (const chai* qName); 
DX_Queue* CreateQueue (const char* qName); 



The ownership of the pointer of a Common Object is 
transferred to DX_Queue Manager after invoking the 
Enqueue( ) method and transferred to the caller process after 
invoking Dequeue( ) method. GetQueueView ( ) obtains a 
snap-shot of a given queue. It has two options: it either gets 
the snap-shot of the entire queue or only the snap-shot on the 
queue of a given priority. Since it can be invoked repeatedly 
to get the snap-shot of a queue page by page, a cursor must 
be defined to record the position of queue in order to get the 
snap shot. Before calling GetQueueView( ), the caller must 
call GetCursor( ) to get the cursor first. The appropriate 
usage is "GetCursor (QueueName)" to get a cursor for the 
entire queue. Calling GetCursor (QueueName, Priority) will 
initialize a cursor for the queue entries of a given priority. 



20 If the user does not pass in the size argument of 
GetQueueView( ), the snap-shot of the entire queue will be 
returned. When the size is passed in, it will be used to limit 
the number of entries returned. In this case, a user may call 
GetQueueView( ) repeatedly to get the next size controlled 

25 block of entries until the list returned is empty list, A user 
may invoke Reset( ) to reset the cursor the beginning of the 
queue, 

DX_Queue is an abstract interface class. It only provides 
an interface for Enqueue/Dequeue operations and Commit/ 
30 Rollback operations. An implementation example is given as 
follows: 

EXAMPLE #58 



class: DX„Queue 
{ 

friend class DX_QueucManager; 

friend DX_Boolean IsQueueEqual(const DX_Queue* queue, const void* value); 
protected: 

virtual - DX_Queue( ); 

virtual EreturaCodes Enqueue(DX_CommonObject& co, const char" Processld, 
const char* label, const char* comment, DX_QueueTransaction& transact, EPriorityCode 
pCode) = 0; 

virtual DX_CommonObject* Dequeue(DX_QueueTransaction& transact) - 0; 
virtual DX_CommonObject* Dequeue(DX_QueueTransaction& transact, const 

char* ObjectID, const char* ObjectLabel) - 0; 

//Only DX_FileQucue need to implemented the following two methods 
virtual EreturaCodes Commit(DX_QueueOperation& oper) {return FAILED;} 
virtual EreturaCodes CompleleCommit(DX_OueueOperation& oper) {return 

FAILED;} 

virtual EreturaCodes RoUback(DX_QueueOperation& oper) {return FAILED;} 
const char* GetQueucName( ) const; 
virtual EreturaCodes DestroyStorage( ) - 0; 
virtual EreturaCodes Flush(EPriorityO>de priority) - 0; 
virtual EreturaCodes RemoveObject(DX_OueucObjcct* qObj) ~ 0; 
virtual EreturaCodes GotoBeginning(EPriorityCode priority, DX_IndexObject 
&cursor) = 0; 

virtual EretumCodes GetQueueView(EPriorityCode priority, DX_IndexObject 
&cursor, 

DX_QueueObjectList* &list, int size) - 0; 
//performance monitor 

virtual void GetQueucPerformance(long "pNumObjcctProcessed, 

double •pAvgMsgCacheTtme, 

double *pAvgMsgProcessTimc ) = 0; 
virtual void Reset( ) = 0; 
//We should not have instance of this class 
DX_Queue(const char* qName); 
in line void SetWeightRootsAndVisitedFlags( ) 

{ 

roots[NONURGENT] « O.Of; 
roots[NORMAL] - 0.6 f; 
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rootst URGENT] = 0.8f; 

roots[ INTERACTIVE] - l.Of; //will always block other priorities 
VisitedFIags[NONURGENT] = 0x01; 
VisitedFlags[iVORMAL] = 0x02; 
VisitcdFlagstURGENTT] = 0x04; 
VisitedFlags[[NTERACnVE3 - 0x08; 

//Because these members should be seen by the derived classes, 

//we keep them as protected. 

Boat roots{NTJM_PRIORITIES]; 

unsigned char VisitedFlags(NUM_PRIORrnES]; 

float weights[NUM_PRIORrnES); 

char *QueueName; 



DX_FileQueue class contains four child queues for each 
priority. Besides the queue operation interface and transac- 
tion interface, the algorithm of priority handling is also 
implemented in this class. The priority algorithm is imple- 
mented inside the Dequeue method. The DX_IndexObject 
argument of the Dequeue methods is used for transaction 
control. At running time, Dequeue operations fill in corre- 
sponding fields in DX_IndexObject, which is a component 
of DX_QueueOperation object. An implementation 
example is given as follows: 

EXAMPLE #59 



DXJileSub Queue is mapped to a set of files of one 
queue of one priority. The internal DX_QueueObjectList 
object acts as a buffer at running time. All the operations will 

20 not be written into files until commit or rollback time. 

Each queue is stored into two categories of files. Each 
Common Object will be stored as a single file, named by its 
OID. These files will be evenly distributed, on the modula of 
256, into different sub-directories for purposes of even file 

25 distribution and performance. These files are generated 
when the object is serialized. The index of each Common 
Object is stored in a series of indexed files, indexed from 0 
to 9999, which is the physical and persistent storage for the 



class: DX_FileQueue : public DX_Queue 
{ 

friend class DX_QueueManager; 
private: 

DX_FileQueue(const char* qName, const char* FileDBDir); 
~DX_FileQueue( ); 

EreturnCodes Enqucuc(DX__CommonObject& co, const char* Process Id, 
const char* label, const char* comment, 
DX_QueueTnmsaction& transact, EPriorityCode pCode>, 

DX_CommoQObject* Dequeue(DX_OueueTransacuon& transact); 

DX_CommonObject* Dequeue(DX_QueueTransaction& transact, 
const char* ObjcctID, const char* ObjcctLabel); 

EreturnCodes Commit(DX_QueueOperation& oper); 

Ereturn Codes CompleteCommit(DX_QueueOperation& oper); 

EreturnCodes RolIback(DX_QueueOperation& oper); 

EreturnCodes DestroyStorage( ); 

EreturnCodes Ftush(EPriorityCode priority); 

EreturnCodes RemoveObject(DX_QueueObjecl* qObj); 

EreturnCodes GotoBeginning(EPriorityCode priority, DX_JndexObject &cursor); 
EreturnCodes GetQueue View (EPriorityCode priority, DX_IndexObject &cursor, 

DX_OueueObjectList* filist, int size); 
//used for the performance monitor 

void GetQueuePerformance(long *numOfMsgProcessed, double 
*avgMsgCacheTime, 

double •avgMsgProcessTime); 

void Reset( ); 
private: 

DX_FUeSubQueue* subqueues[NUM_PRIORrnESj 
DX_Mutex* WeightMutex; 

DX_Mutex* SubOueueMutex[NUM_PRIORTTIES]; 



The dequeuing interface, as previously discussed, uses a 6Q 
weight based priority algorithm. This ensures that the high- 
est priority messages are handled in a timely manner and low 
priority messages are not starved. Each priority level has its 
own base weight. Each time a priority queue is visited, the 
weight of the other priorities is increased by 0.1. If the 
weight of any priority reaches 1.0, it is then processed. The 65 
base weight of the interactive priority is 1 .0, so it will always 
be visited first, thus it can block all the other priorities. 



logic queue. Each file may contain up to 100 index records. 
The order of the index record is defined by the offset of that 
record to the beginning of the file. 

A logical dequeue cursor is also defined and manipulated 
in this class. For purposes of performance, this cursor should 
never be rolled back. This feature is also implemented via 
the help of DX_QueueObjectList class as well. 

The enqueue operation appends a record at the end of the 
newest file. The dequeue operation attempts to find a valid 



06/10/2004, EAST Version: 1.4.1 



US 6,453,356 Bl 



63 



record from the internal memory buffer. If one is not found, 
the dequeue operation will then read one index object from 
file into the memory buffer. A status field is used to deter- 
mine the validity of the record. An object can be marked as 
follows: NEW_OBJECT (object is enqueued but not com- 
mitted yet); ENQUEUED_OBJECT (object is enqueued 
and committed); NORMAL_OBJECT (valid object in the 
queue storage or a the object was rolled back in the memory 
buffer); ACTIVE_OBJECT (object is read from file into 



64 



memory buffer and being processed); or DELETED_ 
OBJECT (object has been processed after it is dequeued or 
it was marked as so in the file). The object in the file storage 
will only be labeled DELETED_OBJECT after the trans- 
action is committed. An implementation example is given as 
follows: 

EXAMPLE #60 



class: DJCJuleSubQueuc 
{ 

friend class DX_FiIeQueue; 
friend class DX_QueueManager, 
private: 

DX_FileSubQucue(const char* qName, EPrioiityCodc pCodc, const char* 
FileDBDir); 

~DX_FileSubQueue( ); 

ErcturnCodes Enqueue (DX_CommonObject& co, const char* Processld, 

const char 1 ' label, const char* comment); 
DX_CommonObject* Dequcue(DX_IndcxObject& io); 
DX_CommonObject* Dequeue(DX_IndexObject& io, const char* ObjectID, 

const char* ObjectLabel); 
EreturnCodes Commit (DX_QueueOperation& opcr); 
EreturnCodes CompleteCommit(DX_QueueOperation& oper); 
EreturnCodes RolLback(DX_QueueOperation& oper); 
EreturnCodes DestroyStorage( ); 
EreturnCodes Flush( ); 

EreturnCodes RemoveObject(DX__QueueObject* qObj); 
EreturnCodes GotoBeginning(DX_IndexObject& cursor); 
EreturnCodes GctQueueVicw(DX_IndexObjcct ftcursor, DX_QucueObjcctList* 
&list, 

int size); 

//used by the performance monitor 
long GetNumOfMsgProcessed( ); 
double GetTotalMsgCacheTimc( ); 
double GetTotalMsgProcessTune( ); 
void Reset( ); 
private: 

char* QueueName; 
EPriorityCode Priority, 
char* QueueFileName; 
char* IndexDirectory; 
int startFilelndex; 
int endFUetndex; 

//These two fields are used for Dequeue operation and always go forward 

int currentFilelndex; 

int currentRecordlndex; 

int lastRecordlndex; 

DX_QueueObjectList BufferLUt; 

IlililllllllliUlillfiilll 

//Internal use only 

////////////////////////// 

EreturnCodes EnqueueCommil(DX_QueueOperation &oper); 
EreturnCodes DequeueCommit(const char* oid, const DX_IndexObject* io); 
EreturnCodes CompleteEnqueucCommit(DX_QueueOperation &oper); 
EreturnCodes CompleteDequeueCommit(const char* oid, const DX__IndexObject* 

io); 

EreturnCodes Enqueue Rollback(const char* oid, const DX_IndexObject* io); 

EreturnCodes Dequeue Rollback(const char* oid, const DX_[ndexObject* io); 

EreturnCodes Try Recycle File(int flndcx); 

void TryRecycleQueue( ); 

char* GetFileNamefint flndex); 

int OpenFile(int whichFiie); 

EreturnCodes CreatEndFi]e( ); 

void UpdateIndexFile( ); 

void UpdateFUeIndex( ); 

EreturnCodes ExpandQueuc( ); 

EreturnCodes MarkObiectInFUe(const DX_IndexObjecf iObj, 

EQueueObjectStatus status); 
//Unix does not have low-level eof IO function available 
int lsEOF(int fd); 
//used by performance monitor 
double totalMsgCacheUme; 
double total MsgProcessTime; 
long numOfMsgCommited; 
void SetDequeueTune(DX_QueueObject *qo); 
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-continued 



void SetEDqueueTime(DX_QueueObjea *qo); 

void CompleteCommitCalculation(DX_OucueObject *qo); 

}; 



Enqueue( ) creates a queue object marked as NEW_ 
OBJECT and inserts it into memory buffer. 
EnqueueCommit( ) serializes Common Object, writes a 
queue object into a queue file and marks the queue object as 
ENQUEUED_OBJECT. CompleteEnqueueCommit( ), 
which is called after all the operations in a transaction have 
been committed successfully, removes a queue object from 
the memory buffer and frees memory of Common Object. 
EnqueueRollback( ) marks the queue object as DELETED_ 
OBJECT in the queue file, deletes the Common Object file, 
removes the queue object from the memory buffer, and frees 
memory of Common Object. 

Dequeue( ) attempts to find a queue object marked as 
NO RMAL_OBJECT first from the memory buffer. If it can 
not find one, it will try to find one from the queue files. If 
Dequeue( ) finds a queue object marked as NORMAL_ 
OBJECT in a file, it creates a queue object, marks it as 
ACTIVE_OBJECT, inserts it into the memory buffer, and 
de-serializes the Common Object it refers to and returns the 
Common Object to the caller. During this process, if 
Dequeue( ) can not de-serialize the Common Object, it will 
mark the queue object as DELETED_OBJECT in the queue 
file and continue its search. 



During the de-serialization process of a Common Object, 
a backup file of the Common Object is created for the 

10 purpose of the Rollback( ) method which can restore it to the 
initial status. DequeueCommit( ) removes the Common 
Object file. CompleteDequeueCommit( ), which is called 
after all operations in a transaction have been committed 

15 successfully, marks the queue object as DELETE_OBJECT 
in the queue file, removes the queue object from the memory 
buffer, and removes the backup file of the Common Object 
created by the Dequeue( ) method. DequeueRollback( ) 
restores the Common Object from the backup file, deletes 

20 the backup file, and marks the queue object as NORMAL_ 
OBJECT in the memory buffer. 

DX_J)BQueue is the database-based implementation of 
the DX_Queue interface. Its instance is mapped to a single 
table per queue at run-time. The order of the records is 
25 determined by the enqueue time stamp. All dequeue opera- 
tions are sorted by priority and enqueue time stamp. An 
illustrative example of a DX__DBQueue implementation is 
provided as follows: 

EXAMPLE #61 



class: DX_DBQueue : public DX_Queue 
{ 

friend class DX_QueueManager; 
private: 

DX_DBQueue(const char* qName); 
~DX_DBOucuc( ); 

EreturnCodes Enqueue (DX_CommonObject& co, coast char* Process Id, 
const char* label, const char* comment, 
DX_QueueTransaction& transaction, EPriorityCode 

priority); 

DX_CommonObjcct* Dcqueue(DX_QucucTransaction &); 
D^CommonObject' 1 Dequeue(DX__QueueTransaction& transaction, int priority); 
DX_CommonObjcct* Dcqucuc(DX_QucucTransaction& transaction, 

const char* ObjectID, const char* Object Label); 
//Virtual methods inherited from DX_Queue and NOT USED 
EreturnCodes Commit (DX_GueucOperation& oper) {return FAILED;} 
EreturnCodes CompleteCommit(DX_QueueOperation& oper) {return FAILED;} 
EreturnCodes Rollback(DX_QucueOpcration& oper) {return FAILED;} 
static EreturnCodes Commit(DX_QuetieTrarisaction& transaction); 
static EreturnCodes Rollback(DX_QueueTransaction& transaction); 
static EreturnCodes Crcatc1able(int DBcontextld, const char* qName); 
EreturnCodes DestroyStorage( ); 
EreturnCodes Rush (EPriorityCode priority); 
EreturnCodes RemoveObject(DX_QiieueObject* qObj); 
EreturnCodes GotoBeginning(EPriorityCode priority, 

DX__IndexObjcct &cursor){rcturn SUCCESS;} 
EreturnCodes GetQueueView(EPriorityCode priority, DX_IndexObject Scursor, 

DX_QucueObjcctList* &list, int size); 
//used for the performance monitor 
void GetQueuePerformanceflong *NumOfMsgProcessed, 

double "avgMsgCacheTiirie, 

double "avgMsgPrccessTune); 
void Resct( ); 

static EreturnCodes GetTableSpaceUsage(float &usage); 

static char** GetAllQueueNames(int& number); 

//Data member 

DX_Mutex* WeightMutex; 

//used by performance monitor 

long *numOfMsgCommited; 

double * total MsgCacheTime; 



06/10/2004, EAST Version: 1.4.1 



US 6,453,356 Bl 
67 68 



-continued 



double 'totalMsgProcessTune; 

static void CommitCalculations(DX_QueueTransactioD &transaction); 

}; 



The DX_IndexObject class is important for all the queue 
operations. It is used to uniquely identify the location at 
which a Common Object is stored, and is further used for 
internal routing of all queue requests. The DX_IndexObject 
class is member of the DX_QueueObject class and 
DX_QueueOperation class. Its members include queue 
name, queue priority, storage type, file handle, file index, 
record offset, and record sequence. An illustrative example 
of a DX_IndexObject implementation is provided as fol- 
lows: 

EXAMPLE #62 



class: DX_IndexObject 
{ 

friend class DX_QueueObject; 
friend class DX_QueueOpe ration; 
friend class DX_FilcSubQucue; 
friend class DX_FileQueue; 
friend class DX_DBQueue; 
friend class DX_QueueManager; 
public: 

//Because GetQucueVicw needs an instance of DX_IndexObject 
as cursor 

//and user should be able free the instance after use 
~DX_IndexObject( ); 
private: 

DX_IadexObjcct(EstorageTVpcs type); 
DX_IndexObject(Estorageiypes type, const char "qName, 
EPriorityCodc priority); 

DX_IndexObject(const DX__IndexObject& inputIO>, 
DX_JndexObject& opera to r-(const DX_IndexObject& 
inputIO); 

in line EstorageTypes GetStorageType( ) const 

return StorageType; 
in line const in t GetFdeHandle( ) const 

return FileHandle; 
in line const char* GetQueueNamef ) const 

return QueueName; 
in line EPriorityCodc GetPriority( ) const 

return Priority; 
in line int GetFilelndexf ) const 

return Filelndex; 
in line long GetRecordOffset( ) const 

return RecordOffset; 
in line long GeOlmeStampC ) const 

return Time Stamp; 

EreturnCodes SetFileHandle(int fh); 
EretumCodes SetQueueName(const char* qName); 
EreturnCodes SetPriority(EPriorityCode priority); 
EretumCodes SctRccordOffsct(long rOffsct); 
EreturnCodes SetFileIndex(int find ex); 
EretumCodes SetTimeStamp(long tm); 



-continued 

10 

private: 

char* QueueName; 
EPriorityCode Priority; 
EstorageTypes StorageType; 
int FileHandle; //handle to a file already opened 
15 int Filctndex; 

long RecordOSset; 

long TimeStamp; //enqueue time 

}; 



20 The invocation of the Enqueue( ) and Dequeue( ) API is 
effected by sending a request to the Queue Manager Object. 
In response to a request, the Queue Manager Object locates 
the correct queue and populates the operations to that queue 
object. When Enqueue( ) is invoked, the object is placed into 
25 a buffer list and will not be collapsed into a data stream until 
Commit( ) is invoked. Until the commit time, the 
DX_IndexObject attribute of the DX_QueueOperation 
object retains the real meaning, which may be used in 
connection with a rollback operation if the commit operation 
30 is not successfully executed. For purposes of serialization, if 
the queue is a database, the row-level locking provided by 
the database is used. If the queue is a file, file access control 
is used. When a Common Object is serialized at commit 
time, a priority tag is appended to its private attribute list, 
35 such that when the Common Object is dequeued, its priority 
can be easily determined. 

When Dequeue( ) is invoked, the oldest entry with the 
proper priority is retrieved with the marshalled object then 
being instantiated as a Common Object using the 
Demarshal( ) method invocation. This mechanism provides 
database row-locking on read events to prevent parallel 
gateways reading the same queued requests. If the queue is 
file based, record lock is used. The logic to determine which 
priority queue should be invoked on implemented inside the 
DX_Queue object. 

A description of the queue record structure will now be 
described. Each queued entry contains the following data: 
OID of the entry in the object table/file that contains the 
flattened object; object label; object status; offset or 
sequence; owner process identification string; and annota- 
tion or comment information. Table 3 below is a graphical 
representation of a typical queue record. 



TABLE 3 



OID 


Object- 
Label 


Priority 


Enqucue- 
Timc 


Processld 


Object- 
Comment 


Type String 


String 


Integer 


Unsigned 
Long 


String 


String 



The Error Queue is needed to provide storage for run-time 
processing failures. Since the entries are stored in a queue 
with an index to the object that generated the error, the 
65 processing logic can decide what further operations should 
be performed. The implementation of Error Queue is as an 
instance of DX__Queue. Since no priority issue is involved 
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in Error Queue, the priority argument of the queue operation 
is relegated to a dummy argument, and only one of the 
internal child queues need be used. 

The Error Queue contains the following data: 01 D of the 
entry in the object table/file that contains the flattened 
object; object label; object status; offset or sequence; owner 
process identification string; and annotation or comment 
information. An Error Queue record has a structure substan- 
tially equivalent to the record structure shown in Table 3 
above. 

Objects are stored and retrieved from a persistent store in 
an efficient manner. Two types of object storage, termed 
relational database storage and file storage, are implemented 
for this purpose. The object persistency is implemented 
using Marshal( ), Demarshal( ), and DeleteStorage( ) meth- 
ods of the DX_CommonObject class, where a parameter is 
passed to indicate storage type. A policy for object caching 
and sharing may also be employed. 

Since database implementation may vary among venders 
and file based persistency is needed, the object persistency 
model has been developed to be independent from any 
database storage technology. This approach involves col- 
lapsing the object into a raw binary data stream, and uses 
various headers to denote any marker and priority related 
information. The headers of a Common Object typically 
include OID and priority tag information. Table 4 provide 
below illustrates a how a Common Object may be stored in 
a typical database. 



TABLE 4 





OID 


Size 


Image 


Column Type 


VARCHAR(128) 


[nTUMBER(IO) 


LONG RAW 



As stated previously, all database access is hidden inside 
the Enqueue( ) and Dequeue( ) methods of 
DX__QueueManager and Marshal( ), Demarshal( ), and 
DeleteStorage( ) methods of DX_CommonObject. In one 
embodiment, all vendor specific access mechanisms may be 
delivered in a separate set of database enabled libraries. 

Serialization and de-serialization optimization refers to 
the ability to collapse and inflate a tree-like object for 
transmission beyond the bounds of a functional block. The 
example below is provided to illustrate usage of the 
Marshal( ), Demarshal( ) methods within this context: 

EXAMPLE #63 

marshal 

void Marshal(int StorageType, int DatabaseContextld); 
demarshal 

void Demarshal(const char* OID, int StorageType, int 
DatabaseContextld); 

It is noted that when serializing and de-serializing an 
object in a Java™ environment, the Rouge Wave Jtools 
Java™ foundation classes may be used since they project a 
broad set of base classes and are compatible with the Rogue 
Wave Tools.h++ classes used in C++. 

File-based database access is invoked using the Marshal( 
), Demarshal( ), and DeleteStorage( ) methods from the 
Common Object with the output argument set to a file. Each 
object may be stored to a separate file where the filename 
incorporates the object ID. By using the object counter 
mechanism as a directory name, files can be spread evenly 
across a file system for better access time. 

In some applications, an ability to perform extended 
transactions may be required to guarantee successful pro- 
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cessing and message delivery. This transaction processing 
does not need to be as full scale as a TP monitor, but it must 
generally be able to guarantee successful completion or 
return of the initial request to its initial state or perform error 
handling. Extended transaction mechanisms are supported 
so that a user can define a run-time transaction and perform 
transactional operations. More specifically, this API includes 
Begin( ), Commit( ), and Rollback( ) operations. 

A transaction object should be created and destroyed as a 
local object of a thread. If neither Commit( ) nor Rollback( 

1 ) was called when a thread exits, all operations executed by 
this thread are rolled back. For a database implementation, 
the native transaction control mechanism of the database is 
used. For a file implementation, a transaction object contains 
a list recording of all operations in the current transaction. 
This memory buffer is used to buffer all queue operations 
and will not be written into file storage until commit time. 
Rollback( ) removes the operations from that memory buffer 
for operations that have not been committed. Since Commit( 
) might fail, Rollback( ) also cleans the entries in the queue 

1 files and Common Object file for those operations that failed 
at commit time. 

To maintain the extended transaction concept and 
operation, a transaction object is passed as an argument for 
each queue operation. The queue manager fills the operation 

' into that transaction object argument so that all queue 
operations are recorded into that transaction object. The 
Commit( ) and Rollback( ) methods of a queue transaction 
object are actually routed to the Commit( ) and Rollback( ) 
methods of the queue manager, which actually performs the 

1 transaction operations. 

Concerning the ownership of pointers, once Enqueue( ) is 
invoked, the DX_QueueManager and its related compo- 
nents take over all ownership of the object's pointer, irre- 
spective of whether either Commit( ) or Rollback( ) will be 

* called later. When Dequeue is invoked, ownership of the 
object's pointer is given to the caller, irrespective of whether 
either Commit( ) or Rollback( ) will be called later. 

The foregoing description of the various embodiments of 
the invention has been presented for the purposes of illus- 

3 tration and description. It is not intended to be exhaustive or 
to limit the invention to the precise form disclosed. Many 
modifications and variations are possible in light of the 
above teaching. It is intended that the scope of the invention 
be limited not by this detailed description, but rather by the 

5 claims appended hereto. 
What is claimed is: 

1. A method of transporting data, comprising: 

receiving a data stream from each of a plurality of source 
applications, each of the data streams comprising infor- 
3 mational content and having a technology dependent 
form associated with a source protocol; 

converting the data streams from the technology depen- 
dent forms to technology independent forms not asso- 
ciated with the respective source protocols and not 
5 associated with respective destination protocols of one 
or more destination applications; 

identifying the one or more destination applications; 

transporting the data streams having the technology inde- 
0 pendent forms; 

transforming the data streams from the technology inde- 
pendent forms to technology dependent forms associ- 
ated with the respective destination protocols of the one 
or more of the destination applications; and 
65 transmitting all or a portion of the data streams having the 
technology dependent forms to the one or more of the 
destination applications. 
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2. The method of claim 1, further comprising processing 
the data streams using pre-established logic associated with 
each of the data streams. 

3. The method of claim 2, wherein the pre-established 
logic associated with each of the data streams is alterable by 5 
a user. 

4. The method of claim 1, wherein transmitting the data 
streams comprises transmitting the data streams asynchro- 
nously or pseudo-synchronously to the destination applica- 
tions. 10 

5. The method of claim 1, wherein identifying one or 
more destination applications comprises applying routing 
logic associated with each of the data streams to facilitate 
transmission of the data streams to the destination applica- 
tions. 15 

6. The method of claim 5, wherein the routing logic is 
alterable by a user. 

7. The method of claim 1, further comprising tracking 
each of the data streams during converting, identifying, or 
transforming operations. 20 

8. The method of claim 7, further comprising logging 
errors occurring during converting, identifying, or trans- 
forming operations. 

9. The method of claim 1, further comprising validating 
the data streams. 25 

10. A method of transporting data, comprising: 
receiving, from a source application, data comprising 

informational content in a technology dependent form 
associated with a source protocol; 

converting the data from the technology dependent form 
associated with the source application to a technology 
independent form not associated with the source pro- 
tocol and not associated with respective destination 
protocols of one or more destination applications; ^ 

identifying the one or more destination applications; 

transporting the data having the technology independent 
form; 

transforming the data from the technology independent 
form to a technology dependent form associated with 40 
the respective destination protocols of the one or more 
of the destination applications; and 

transmitting all or a portion of the data in the technology 
dependent form to the one or more of the destination 
applications. 45 

11. The method of claim 10, further comprising process- 
ing the data in the technology independent form. 

12. The method of claim 11, wherein processing the data 
comprises altering the data according to pre-established 
logic. 50 

13. The method of claim 12, wherein the pre-established 
logic is alterable by a user. 

14. The method of claim 10, wherein transmitting the data 
comprises transmitting the data asynchronously or pseudo- 
synchronously to the destination applications. 55 

15. The method of claim 10, wherein identifying one or 
more destination applications comprises applying routing 
logic to facilitate transmission of the data to the destination 
applications. 

16. The method of claim 15, wherein the routing logic is 60 
alterable by a user. 

17. The method of claim 10, further comprising tracking 
the data during converting, identifying, or transforming 
operations. 

18. The method of claim 17, further comprising logging 65 
errors occurring during converting, identifying, or trans- 
forming operations. 
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19. A method of transporting data, comprising: 
receiving data from a source application, the data com- 
prising information associated with a source format; 

disassociating the information from its associated source 
format; 

converting the disassociated information to information 
having a generic format not associated with the source 
application and not associated with one or more desti- 
nation applications; 

identifying the one or more destination applications; 

transporting the information having the generic format; 

transforming the information having the generic format to 
information having a format compatible with the 
respective one or more of the destination applications, 
the formats of the one or more of the destination 
applications being dissimilar to the source format; and 

transmitting all or a portion of the transformed informa- 
tion to the one or more of the destination applications. 

20. The method of claim 19, further comprising process- 
ing the information having the generic format using pre- 
established business logic. 

21. The method of claim 20, further comprising altering 
the business logic by a user. 

22. The method of claim 19, further comprising applying 
routing logic to facilitate transmission of the transformed 
information to the destination applications. 

23. The method of claim 22, further comprising altering 
the routing logic by a user. 

24. The method of claim 19, wherein transmitting the 
transformed information further comprises asynchronously 
or pseudo-synchronously transmitting the transformed infor- 
mation to the destination applications. 

25. The method of claim 19, further comprising: 
tracking processing of the information having the generic 

format; and 

logging errors occurring during the processing of the 
information having the generic format. 

26. The method of claim 19, further comprising producing 
performance data associated with processing of the infor- 
mation having the generic format. 

27. The method of claim 19, further comprising validating 
the received data, 

28. A system for transporting data among applications, 
comprising: 

an input data adapter comprising an input interface and an 
input data converter, the input interface receiving an 
input data stream comprising informational content and 
having a technology dependent form associated with a 
source protocol of a source application, the input data 
converter converting the input data stream having the 
technology dependent form to input data having a 
technology independent form not associated with the 
source protocol and not associated with a plurality of 
destination applications; 

a processor communicatively coupled to the input adapter 
and coordinating the input data having the technology 
independent form, the processor coordinating transmis- 
sion of all or a portion of the input data to the plurality 
of destination applications; and 

a plurality of output adapters each communicatively 
coupled to the processor and a respective one of the 
plurality of destination applications, each of the output 
adapters comprising an output data converter that con- 
verts the input data having the technology independent 
form to an output data stream having a technology 
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dependent form associated with a destination protocol 
compatible with a respective destination application, 
and each of the output adapters further comprising an 
output interface that transmits the output data stream to 
the respective destination application. 5 

29. The system of claim 28, wherein the input data adapter 
implements logic for processing the input data stream hav- 
ing the technology dependent form. 

30. The system of claim 28, wherein each of the output 
data adapters implements logic for processing the input data 1Q 
having the technology independent form. 

31. The system of claim 29, further comprising an inter- 
face for altering the logic by a user. 

32. The system of claim 30, further comprising an inter- 
face for altering the logic by a user. 

33. The system of claim 28, wherein the processor com- 15 
prises a plurality of distributed processing units. 

34. The system of claim 28, wherein the processor is 
coupled to a receive queue and a plurality of send queues, 
the receive queue receiving the input data having the tech- 
nology independent form from the input data adapter and the 20 
processor coordinating transmission of all or a portion of the 
input data having the technology independent form to one or 
more of the send queues. 

35. The system of claim 34, wherein the processor com- 
municates control signals to the send queues to coordinate 15 
transmission of all or a portion of the input data having the 
technology independent form to one or more of the output 
data adapters. 

36. The system of claim 35, wherein processor coordi- 
nates transmission of the input data having the technology 30 
independent form to one or more of the output data adapters 

in an asynchronous or pseudo-synchronous manner. 

37. The system of claim 28, wherein the receive queue 
operates as a first-infirst-out buffer. 

38. A system for transporting data among applications, 35 
comprising: 

a plurality of input data adapters each comprising an Input 
interface and an input data converter, each of the input 
interfaces receiving an input data stream comprising 
informational content and having a technology depen- 40 
dent form associated with a source protocol of a 
respective source application, the input data converters 
converting the input data streams having technology 
dependent forms to input data streams having technol- 



40. The system of claim 38, wherein each of the output 
data adapters implements logic for processing the output 
data stream having the technology dependent form compat- 
ible with the respective destination application. 

41. The system of claim 38, wherein the processor com- 
prises a plurality of distributed processing units. 

42. The system of claim 38, wherein the processor is 
coupled to a receive queue and a plurality of send queues, 
the receive queue receiving the input data streams from the 
input data adapters and the processor coordinating transmis- 
sion of all or a portion of the input data streams having 
technology independent forms to the send queues. 

43. The system of claim 42, wherein the processor com- 
municates control signals to the send queues to coordinate 
transmission of the input data streams having technology 
independent forms to one or more of the output data adapters 
in an asynchronous or pseudo-synchronous manner. 

44. A computer readable medium tangibly embodying a 
program executable for transporting data, comprising: 

receiving, from a source application, data comprising 
informational content in a technology dependent form 
associated with a source protocol; 

converting the data from the technology dependent form 
associated with the source application to a technology 
independent form not associated with the source pro- 
tocol and not associated with destination protocols 
associated with one or more destination applications; 

identifying the one or more of the destination applica- 
tions; 

transporting the data having the technology independent 
form; 

transforming the data from the technology independent 
form to a technology dependent form comprising a 
destination protocol associated with each of the one or 
more of the destination applications; and 

transmitting all or a portion of the data in the technology 
dependent form to the one or more of the destination 
applications. 

45. The medium of claim 44, further comprising altering 
the data according to pre-established logic. 

46. The medium of claim 45, wherein the pre-established 
logic is alterable by a user. 

47. (New) The medium of claim 44, wherein identifying 
one or more destination applications comprises applying 
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tive source protocols and not associated with a plurality 
of destination applications; 

a processor communicatively coupled to the input adapt- 
ers and coordinating the input data streams having the 
technology independent form, the processor coordinat- 50 
ing transmission of all or a portion of the input data 
streams having the technology independent form to the 
plurality of destination applications; and 

a plurality of output adapters each communicatively 
coupled to the processor and a respective one of the 55 
plurality of destination applications, each of the output 
adapters comprising an output data converter that con- 
verts a respective input data stream having the tech- 
nology independent form to an output data stream 
having a technology dependent form associated with a 60 
destination protocol compatible with a respective des- 
tination application, and further comprising an output 
interface that transmits the output data stream to the 
respective destination application. 

39. The system of claim 38, wherein each of the input data 65 
adapters implements logic for processing the respective 
input data stream having the technology dependent form. 



destination applications. 

48. The medium of claim 47, wherein the routing logic is 
alterable by a user. 

49. The medium of claim 44, further comprising tracking 
the data during converting, identifying, or transforming 
operations. 

50. The method of claim 49, further comprising logging 
errors occurring during converting, identifying, or trans- 
forming operations. 

51. A system for transporting data, comprising: 
means for receiving data comprising informational con- 
tent in a technology dependent form associated with a 
source protocol from a source application; 

means for converting the data from the technology depen- 
dent form to a technology independent form not asso- 
ciated with the source protocol and not associated with 
destination protocols associated with one or more des- 
tination applications; 

means for identifying the one or more destination appli- 
cations; 

means for transporting the data having the technology 
independent form; 
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means for transforming the data from the technology 
independent form to a technology dependent form 
comprising a destination protocol associated with each 
of the one or more of the destination applications; and 

means for transmitting all or a portion of the data in the 
technology dependent form to the one or more of the 
destination applications. 

52. The system of claim 51, further comprising means for 
altering the data according to pre-established logic. 

53. The system of claim 52, further comprising means for 
altering the pre-established logic by a user. 
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54. The system of claim 51, further comprising means for 
applying routing logic to facilitate transmission of the data 
to the destination applications. 

55. The system of claim 54, further comprising means for 
altering the routing logic by a user. 

56. The system of claim 51, further comprising means for 
tracking the data during converting, identifying, or trans- 
forming operations. 

10 

* * * * * 
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